From a6419bde7b568fe1aa638e3adf6740bda3fdefab Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sat, 7 Aug 2021 21:45:14 -0400 Subject: [PATCH 1/5] docs: add custom config for docs site --- package.json | 2 ++ site/_config_docset.yml | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 site/_config_docset.yml diff --git a/package.json b/package.json index 30e12dd3c6..2febcee4df 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,7 @@ "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", @@ -53,6 +54,7 @@ "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 data && 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}'", diff --git a/site/_config_docset.yml b/site/_config_docset.yml new file mode 100644 index 0000000000..67a0a540f5 --- /dev/null +++ b/site/_config_docset.yml @@ -0,0 +1,36 @@ +# Config for building a docset +# Initially created by Dash, but supported by several OSS tools too +# (Velocity, Zeal, etc) + +title: Vega-Lite +description: Bare SEO for offline usage + +# removing baseurl b/c dash docsets don't work with absolute paths +# end up needing the +# if this doesn't work out, rewrite all link refs using BS4 later... + +# using https://ricostacruz.com/til/relative-paths-in-jekyll as workaround + +baseurl: '.' # the subpath of your site, e.g. /blog/ +url: 'https://vega.github.io' # the base hostname & protocol for your site +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-sitemap + # - jekyll-seo-tag + - jekyll-mentions + - jekyll-redirect-from From b715dee45de0cccbb3a3a3f9a777a72dcb9d9d18 Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sat, 7 Aug 2021 23:01:41 -0400 Subject: [PATCH 2/5] build: adjust links in site config to support file-system based documentation browsing --- .vscode/settings.json | 7 ++++++- site/_config.yml | 1 + site/_config_docset.yml | 3 ++- site/_layouts/base.html | 9 +++++++-- site/_layouts/plain.html | 6 +++--- 5 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index bc2d8b2f46..8b39ed90bd 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -17,7 +17,12 @@ "typescript.tsdk": "node_modules/typescript/lib", "typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces": false, "typescript.referencesCodeLens.enabled": true, - "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"], + "eslint.validate": [ + "javascript", + "javascriptreact", + "typescript", + "typescriptreact" + ], "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }, diff --git a/site/_config.yml b/site/_config.yml index 35de4a2c82..74af815af3 100644 --- a/site/_config.yml +++ b/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 diff --git a/site/_config_docset.yml b/site/_config_docset.yml index 67a0a540f5..10499e0a44 100644 --- a/site/_config_docset.yml +++ b/site/_config_docset.yml @@ -11,8 +11,9 @@ description: Bare SEO for offline usage # using https://ricostacruz.com/til/relative-paths-in-jekyll as workaround -baseurl: '.' # the subpath of your site, e.g. /blog/ +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: diff --git a/site/_layouts/base.html b/site/_layouts/base.html index 54156d76e7..439560dbff 100644 --- a/site/_layouts/base.html +++ b/site/_layouts/base.html @@ -7,11 +7,16 @@ - {% seo %} - + {% if site.is_docset_build == true %} + + {% else %} {% seo %} + {% endif %} diff --git a/site/_layouts/plain.html b/site/_layouts/plain.html index 9a77ddbc73..a4dff759b0 100644 --- a/site/_layouts/plain.html +++ b/site/_layouts/plain.html @@ -6,7 +6,7 @@