feat(build): modify docs navigation hrefs for compatibility with offline documentation

.ruby-version

@@ -0,0 +1 @@
+3.2.3

package.json

@@ -46,13 +46,15 @@
     "build:toc": "yarn build:jekyll && scripts/generate-toc",
     "build:site": "rollup -c site/rollup.config.mjs",
     "build:jekyll": "pushd site && bundle exec jekyll build -q && popd",
+    "build:docset": "pushd site && bundle exec jekyll build -c _config_docset.yml -q && popd",
     "build:versions": "scripts/update-version.sh",
     "clean": "yarn clean:build && del-cli 'site/data/*' 'examples/compiled/*.png' && find site/examples ! -name 'index.md' ! -name 'data' -type f -delete",
     "clean:build": "del-cli 'build/*' !build/vega-lite-schema.json",
     "data": "rsync -r node_modules/vega-datasets/data/* site/data",
     "schema": "mkdir -p build && ts-json-schema-generator -f tsconfig.json -p src/index.ts -t TopLevelSpec --no-type-check --no-ref-encode > build/vega-lite-schema.json && yarn renameschema && cp build/vega-lite-schema.json site/_data/",
     "renameschema": "scripts/rename-schema.sh",
     "presite": "yarn data && yarn schema && yarn build:site && yarn build:versions && scripts/create-example-pages.sh",
+    "docset": "yarn schema && yarn build:site && yarn build:docset && yarn build:versions && scripts/create-example-pages.sh",
     "site": "yarn site:only",
     "site:only": "pushd site && bundle exec jekyll serve -I -l && popd",
     "prettierbase": "prettier '**/*.{md,css,yml}'",

site/_config.yml

@@ -12,6 +12,7 @@ exclude:
   - Gemfile
   - Gemfile.lock
   - static/*.ts
+is_docset_build: false # Control behaviors that make it easier to replace absolute with relative paths for offline friendly builds. False for deploying to the public docs.
 
 markdown: kramdown
 highlighter: none

site/_config_docset.yml

@@ -0,0 +1,35 @@
+# Config for building a docset
+# For usage: https://github.com/hydrosquall/vega-lite-docset-generator
+
+title: Vega-Lite
+description: N/A
+
+# Alternative: Rewrite the paths to relative URLs locally
+# None of these worked when simply applied to base.html, so I ended up transforming
+# the base URL in my python script instead. Leaving notes in here for posterity.
+# https://ricostacruz.com/til/relative-paths-in-jekyll
+# https://gist.github.com/Ketrel/1f36fca6b4148f7263b3ee8fdb0923e7
+# https://github.com/jekyll/jekyll/issues/6360
+
+baseurl: 'DOCSET_BASE_TO_REPLACE' # the subpath of your site, e.g. /blog/
+url: 'https://vega.github.io' # the base hostname & protocol for your site
+is_docset_build: true
+twitter:
+  username: vega_vis
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - static/*.ts
+
+markdown: kramdown
+highlighter: none
+
+kramdown:
+  input: GFM
+  auto_id_stripping: true
+  syntax_highlighter_opts:
+    disable: true
+
+plugins:
+  - jekyll-mentions
+  - jekyll-redirect-from

site/_layouts/base.html

@@ -7,11 +7,16 @@
 
     <link rel="shortcut icon" href="https://vega.github.io/favicon.ico" />
 
-    {% seo %}
-
+    {% if site.is_docset_build == true %}
+    <script>
+      // Docset doesn't serve JSON from a fileserver, so it needs to load data from github
+      const BASEURL = 'https://vega.github.io/vega-lite/';
+    </script>
+    {% else %} {% seo %}
     <script>
       const BASEURL = window.location.origin + '{{site.baseurl}}';
     </script>
+    {% endif %}
 
     <link rel="stylesheet" href="{{ site.baseurl }}/static/github.css" />
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/build/font/octicons.min.css" />

site/_layouts/page_submenu.html

@@ -25,7 +25,7 @@
       <br>
       {% else %}
       <li class="sidebar-nav-item"><a {% if link.url == url %}aria-current="page"{% endif %}
-          href="{{site.baseurl}}{{layout.base}}{% if link.url != 'index' %}{{link.url}}.html{% endif %}" title="{{link.title}}">{{link.text}}
+          href="{{site.baseurl}}{{layout.base}}{{link.url}}.html" title="{{link.title}}">{{link.text}}
       </a></li>
       {% if link.sub-sidebar %}
       <ul class="sub-sub-nav">

site/_layouts/plain.html

@@ -15,9 +15,9 @@
       </div>
       <div class="vl-links">
         <div class="primary-links">
-          <a href="{{ site.baseurl }}/examples/" {% if page.menu == 'examples' %}aria-current="page"{% endif %}>Examples</a>
+          <a href="{{ site.baseurl }}/examples/index.html" {% if page.menu == 'examples' %}aria-current="page"{% endif %}>Examples</a>
           <a href="{{ site.baseurl }}/tutorials/getting_started.html" {% if page.menu == 'tutorials' %}aria-current="page"{% endif %}>Tutorials</a>
-          <a href="{{ site.baseurl }}/docs/" {% if page.menu == 'docs' %}aria-current="page"{% endif %}>Documentation</a>
+          <a href="{{ site.baseurl }}/docs/index.html" {% if page.menu == 'docs' %}aria-current="page"{% endif %}>Documentation</a>
           <a href="{{ site.baseurl }}/usage/embed.html" {% if page.menu == 'usage' %}aria-current="page"{% endif %}>Usage</a>
           <a href="{{ site.baseurl }}/ecosystem.html" {% if page.menu == 'ecosystem' %}aria-current="page"{% endif %}>Ecosystem</a>
         </div>