Set up parceljs (#389)

* Set up parceljs

* Fix static file

* Add map files

* Fix EmbeddedResource

* Naming

* Remove duplicate sphinx script

* Add `./build.sh watch` to integrate all continuous builds. (#390)

All continuous builds are now servicable through `dotnet watch`

> dotnet watch --project src/docs-builder --no-hot-reload -- serve

Will build web assets without recompiling c# or rebooting the server.

C# or cshtml changes will rebuild automatically.

Markdown files will continue to be server through liverload without a full restart.

Co-authored-by: Jan Calanog <[email protected]>

---------

Co-authored-by: Martijn Laarman <[email protected]>

.github/actions/bootstrap/action.yml

@@ -30,4 +30,11 @@ runs:
         echo "Version Number: ${REPO_VERSION}"
         echo "REPO_VERSION=${REPO_VERSION}" >> $GITHUB_ENV
         echo "full-version=${REPO_VERSION}" >> $GITHUB_OUTPUT
-        echo "major-version=$(echo ${REPO_VERSION} | cut -d"." -f1)" >> $GITHUB_OUTPUT
+        echo "major-version=$(echo ${REPO_VERSION} | cut -d"." -f1)" >> $GITHUB_OUTPUT
+        
+    - uses: actions/setup-node@v4
+      with:
+        cache: npm
+        cache-dependency-path: src/Elastic.Markdown/package-lock.json
+        node-version-file: .nvmrc
+

.nvmrc

@@ -0,0 +1 @@
+22.13.1

README.md

@@ -137,6 +137,29 @@ To test performance it's best to build the binary and run outside of docker:
 For reference here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
 existing surveyed tools
 
+# Local Development
+
+## Preqrequisites
+
+- [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
+- [Node.js 22.13.1 (LTS)](https://nodejs.org/en/blog/release/v22.13.1)
+
+
+## Continuously build all assets during development.
+
+```shell
+./build.sh watch
+```
+
+This will monitor code, cshtml template files & static files and reload the application
+if any changes.
+
+Web assets are reloaded through `parcel watch` and don't require a recompilation.
+
+Markdown files are refreshed automatically through livereload
+
+Code or layout changes will relaunch the server automatically
+
 # Release Process
 
 This section outlines the process for releasing a new version of this project.

build/CommandLine.fs

@@ -17,7 +17,8 @@ type Build =
     | [<CliPrefix(CliPrefix.None);SubCommand>] Test
 
     | [<CliPrefix(CliPrefix.None);SubCommand>] Format
-
+    | [<CliPrefix(CliPrefix.None);SubCommand>] Watch
+
     | [<CliPrefix(CliPrefix.None);Hidden;SubCommand>] Lint
     | [<CliPrefix(CliPrefix.None);Hidden;SubCommand>] PristineCheck
     | [<CliPrefix(CliPrefix.None);Hidden;SubCommand>] ValidateLicenses
@@ -46,7 +47,9 @@ with
             | Release -> "runs build, tests, and create and validates the packages shy of publishing them"
             | Publish -> "Publishes artifacts"
             | Format -> "runs dotnet format"
-
+
+            | Watch -> "runs dotnet watch to continuous build code/templates and web assets on the fly"
+
             // steps
             | Lint
             | PristineCheck

build/Targets.fs

@@ -35,6 +35,8 @@ let private version _ =
 
 let private format _ = exec { run "dotnet" "format" "--verbosity" "quiet" }
 
+let private watch _ = exec { run "dotnet" "watch" "--project" "src/docs-builder" "--no-hot-reload" "--" "serve" }
+
 let private lint _ =
     match exec {
         exit_code_of "dotnet" "format" "--verify-no-changes"
@@ -167,6 +169,7 @@ let Setup (parsed:ParseResults<Build>) =
                 release
 
         | Format -> Build.Step format
+        | Watch -> Build.Step watch
 
         // steps
         | Lint -> Build.Step lint

src/Elastic.Markdown/.gitignore

@@ -0,0 +1,6 @@
+.parcel-cache/
+node_modules/
+_static/main.js
+_static/main.js.map
+_static/styles.css
+_static/styles.css.map

src/Elastic.Markdown/Assets/styles.css

@@ -0,0 +1,8 @@
+@import "legacy/pygments.css";
+@import "legacy/shibuya.css";
+@import "legacy/mystnb.css";
+@import "legacy/copybutton.css";
+@import "legacy/togglebutton.css";
+@import "legacy/sphinx-design.min.css";
+@import "legacy/custom.css";
+@import "legacy/atom-one-light.css";

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -13,6 +13,40 @@
     <IsPublishable>true</IsPublishable>
     <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
   </PropertyGroup>
+
+  <!-- source https://www.meziantou.net/running-npm-tasks-when-building-a-dotnet-project.htm -->
+  <!--
+    1. Install npm packages
+    "Inputs" and "Outputs" are used for incremental builds. If all output items are up-to-date, MSBuild skips the target.
+    The first time the task is executed. Then, it only runs when you change the package.json file.
+    Documentation: https://learn.microsoft.com/en-us/visualstudio/msbuild/incremental-builds?WT.mc_id=DT-MVP-5003978
+ -->
+  <Target Name="NpmInstall" Inputs="package.json" Outputs="node_modules/.install-stamp">
+    <Exec Command="npm ci" WorkingDirectory="$(MSBuildThisFileDirectory)" ConsoleToMsBuild="true" />
+
+    <!-- Write the stamp file, so incremental builds work -->
+    <Touch Files="node_modules/.install-stamp" AlwaysCreate="true" />
+  </Target>
+
+  <!--
+      2. Run npm run build before building the .NET project.
+      MSBuild runs NpmInstall before this task because of the DependsOnTargets attribute.
+   -->
+  <Target Name="NpmRunBuild" DependsOnTargets="NpmInstall" BeforeTargets="BeforeBuild">
+    <Exec Command="npm run build" WorkingDirectory="$(MSBuildThisFileDirectory)" ConsoleToMsBuild="true">
+      <Output TaskParameter="ConsoleOutput" PropertyName="OutputOfExec" />
+    </Exec>
+  </Target>
+
+  <Target Name="EmbedGeneratedAssets" AfterTargets="NpmRunBuild">
+    <ItemGroup>
+      <EmbeddedResource Include="_static/*.js" Watch="false" />
+      <EmbeddedResource Include="_static/*.js.map" Watch="false" />
+      <EmbeddedResource Include="_static/*.css" Watch="false" />
+      <EmbeddedResource Include="_static/*.css.map" Watch="false" />
+      <EmbeddedResource Include="_static/*.svg" />
+    </ItemGroup>
+  </Target>
 
   <ItemGroup>
     <PackageReference Include="DotNet.Glob" Version="3.1.3" />
@@ -26,8 +60,5 @@
     <PackageReference Include="YamlDotNet" Version="16.1.3" />
     <PackageReference Include="System.IO.Abstractions" Version="21.0.29" />
   </ItemGroup>
-  <ItemGroup>
-    <EmbeddedResource Include="_static/*.js" />
-    <EmbeddedResource Include="_static/*.css" />
-  </ItemGroup>
+
 </Project>

src/Elastic.Markdown/Slices/Layout/_Head.cshtml

@@ -7,15 +7,8 @@
 	<link rel="index" title="Index" href="@Model.Link("genindex.html")"/>
 	<link rel="search" title="Search" href="@Model.Link("search.html")"/>
 	<link rel="next" title="Elastic content" href="elastic/index.html"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("pygments.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("shibuya.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("mystnb.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("copybutton.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("togglebutton.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("sphinx-design.min.css")"/>
-	<link media="print" rel="stylesheet" type="text/css" href="@Model.Static("/_static/print.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("custom.css")"/>
-	<link rel="stylesheet" type="text/css" href="@Model.Static("atom-one-light.css")"/>
+	<link rel="stylesheet" type="text/css" href="@Model.Static("styles.css")"/>
+	<link media="print" rel="stylesheet" type="text/css" href="@Model.Static("print.css")"/>
 	<link rel="preconnect" href="https://fonts.googleapis.com">
 	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 	<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -28,4 +21,4 @@
 	<meta property="og:type" content="website"/>
 	<meta property="og:title" content="Elastic Docs v3"/>
 	<meta name="twitter:card" content="summary"/>
-</head>
+</head>

src/Elastic.Markdown/Slices/Layout/_Scripts.cshtml

@@ -1,8 +1,8 @@
 @inherits RazorSlice<LayoutViewModel>
+<script src="@Model.Static("main.js")"></script>
 <script src="@Model.Static("documentation_options.js")"></script>
 <script src="@Model.Static("doctools.js")"></script>
 <script src="@Model.Static("sphinx_highlight.js")"></script>
-<script src="@Model.Static("sphinx_highlight.js")"></script>
 <script>let toggleHintShow = 'Click to show';</script>
 <script>let toggleHintHide = 'Click to hide';</script>
 <script>let toggleOpenOnPrint = 'true';</script>