From 03e8fb89e6f3b4682d84c5fe0de2c043fd93854e Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Mon, 11 May 2026 14:22:24 +0530 Subject: [PATCH 1/6] add DocumenterVitepress support to DocsDocumenter action --- DocsDocumenter/action.yml | 14 ++++++++++++-- README.md | 1 + 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/DocsDocumenter/action.yml b/DocsDocumenter/action.yml index aee989f..3a4ace5 100644 --- a/DocsDocumenter/action.yml +++ b/DocsDocumenter/action.yml @@ -54,6 +54,10 @@ inputs: description: 'Whether to deploy the docs to the gh-pages branch' required: false default: 'true' + use-vitepress: + description: 'Whether to use DocumenterVitepress.deploydocs() instead of Documenter.deploydocs() for deployment. Requires DocumenterVitepress to be listed in the docs Project.toml.' + required: false + default: 'false' post-preview-comment: description: 'Whether to post a pull request preview comment after deployment' required: false @@ -142,8 +146,14 @@ runs: # Must pass `root` when `deploydocs()` is run from outside make.jl file # Also, `root` must be an absolute path (hence the call to `pwd()`) run: | - using Documenter - deploydocs(; root=pwd(), repo="github.com/${{ github.repository }}.git", dirname="${{ inputs.dirname }}", tag_prefix="${{ inputs.tag_prefix }}", push_preview=true) + use_vitepress = "${{ inputs.use-vitepress }}" == "true" + if use_vitepress + using DocumenterVitepress + DocumenterVitepress.deploydocs(; root=pwd(), repo="github.com/${{ github.repository }}.git", dirname="${{ inputs.dirname }}", tag_prefix="${{ inputs.tag_prefix }}", push_preview=true) + else + using Documenter + deploydocs(; root=pwd(), repo="github.com/${{ github.repository }}.git", dirname="${{ inputs.dirname }}", tag_prefix="${{ inputs.tag_prefix }}", push_preview=true) + end env: GITHUB_TOKEN: ${{ github.token }} JULIA_DEBUG: Documenter diff --git a/README.md b/README.md index 2b45fa0..7a6b30c 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ If your `docs/make.jl` file contains a call to `deploydocs()`, it is not a big d | `julia-version` | Julia version to use | `'1'` | | `exclude-paths` | JSON array of filepath patterns to exclude from navbar insertion | `"[]"` | | `deploy` | Whether to deploy to the `gh-pages` branch or not | `true` | +| `use-vitepress` | Use `DocumenterVitepress.deploydocs()` instead of `Documenter.deploydocs()`. Requires `DocumenterVitepress` in the docs `Project.toml`. | `false` | | `post-preview-comment` | Whether to post the sticky pull request preview comment after deployment | `true` | ### Outputs From b88497b7d1b86a6a183fe39aa06ef833a34e5770 Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Sun, 17 May 2026 15:28:32 +0530 Subject: [PATCH 2/6] DocsDocumenter: expose GITHUB_TOKEN to the build step DocumenterVitepress's writer calls `Documenter.deploy_folder(...)` while `makedocs()` runs in order to compute the `bases` list it writes to `build/bases.txt`. `deploy_folder` requires `GITHUB_TOKEN` to recognise a CI build; without it the writer falls back to `all_ok=false, subfolder=""`, bases.txt ends up empty, and the deploy step then logs "Found no bases suitable for deployment" and exits without deploying. Plumbing the token through the build step fixes PR-preview deploys end-to-end for downstream packages that use `use-vitepress: 'true'` (observed on TuringLang/JuliaBUGS.jl#453). Co-Authored-By: Claude --- DocsDocumenter/action.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/DocsDocumenter/action.yml b/DocsDocumenter/action.yml index 3a4ace5..7123422 100644 --- a/DocsDocumenter/action.yml +++ b/DocsDocumenter/action.yml @@ -116,6 +116,14 @@ runs: - name: Build docs shell: bash run: julia --project=${{ inputs.doc-path }} ${{ inputs.doc-make-path }} + # `DocumenterVitepress`'s writer calls `Documenter.deploy_folder(...)` + # at build time to decide the `bases` it writes to `build/bases.txt`. + # `deploy_folder` requires `GITHUB_TOKEN` to be present to recognise + # a CI build; without it the writer falls back to `all_ok=false`, + # `subfolder=""`, and the later deploy step finds an empty bases list + # and skips. Expose the token so PR-preview deploys work end-to-end. + env: + GITHUB_TOKEN: ${{ github.token }} # We want to use the same version of DocsNav. In principle we would like # to write `uses: TuringLang/actions/DocsNav@${{ github.action_ref }}`, From 025e7d68065f32c0746abaab727f009206a47415 Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Sun, 17 May 2026 15:49:37 +0530 Subject: [PATCH 3/6] DocsNav: make TuringNavbar coexist with DocumenterVitepress MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The static HTML navbar is inserted right after , but Vitepress's own .VPNav / .VPNavBar / .VPLocalNav are `position: fixed; top: 0` — they overlap the TuringLang navbar end-to-end. The existing CSS in TuringNavbar.html only handles Documenter HTML's `.docs-sidebar` / `#documenter`, which don't exist in a Vitepress build. Add a "DocumenterVitepress Tweaks" block that nudges every Vitepress top-pinned element down by `--navbar-height`. The selectors only match Vitepress output, so Documenter HTML rendering is unaffected. Co-Authored-By: Claude --- DocsNav/scripts/TuringNavbar.html | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/DocsNav/scripts/TuringNavbar.html b/DocsNav/scripts/TuringNavbar.html index fd9fca4..38d93e2 100644 --- a/DocsNav/scripts/TuringNavbar.html +++ b/DocsNav/scripts/TuringNavbar.html @@ -22,6 +22,29 @@ } /* End of Documenter.jl Tweaks */ + /* DocumenterVitepress CSS Overrides: + Vitepress fixes its own nav and sidebar to the top of the viewport, + which would overlap the TuringLang navbar inserted just inside . + Push everything Vitepress-side down by --navbar-height so the two stack + cleanly. Only fires when these Vitepress classes are present, so it + has no effect on Documenter HTML output. */ + .VPNav, + .VPNavBar, + .VPLocalNav, + .VPLocalNavOuterContainer { + top: var(--navbar-height) !important; + } + .VPSidebar { + padding-top: var(--navbar-height) !important; + } + .VPContent.has-sidebar, + .VPContent.is-home, + .VPDoc, + .VPHome { + padding-top: var(--navbar-height) !important; + } + /* End of DocumenterVitepress Tweaks */ + /* Color and Font Variables */ :root { --heading-color: #6c757d; From 632eaeaf93cd48f65779ad238c7aed3d6c6afaa2 Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Sun, 17 May 2026 15:59:04 +0530 Subject: [PATCH 4/6] DocsNav: inherit Vitepress design tokens for the TuringLang navbar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When the rendered site is a Vitepress build, the TuringNavbar previously stayed pinned to its own hardcoded palette (`--primary-bg: white`, Source Sans Pro, heavy box-shadow) regardless of Vitepress's light/dark toggle. Visually the result was two stacked headers with totally different colour and typography on the same page (jarring on TuringLang/JuliaBUGS.jl#453). `html:has(.VPNavBar)` rebinds the navbar's CSS variables to Vitepress's own design tokens (`--vp-c-bg`, `--vp-c-text-1`, `--vp-c-brand-1`, `--vp-font-family-base`, ...) so the navbar follows the theme. Also trade the navbar's heavy shadow for a 1px divider so the boundary with the Vitepress nav below reads as one continuous chrome. Documenter HTML output is unaffected — `:has(.VPNavBar)` simply doesn't match anything there. Co-Authored-By: Claude --- DocsNav/scripts/TuringNavbar.html | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/DocsNav/scripts/TuringNavbar.html b/DocsNav/scripts/TuringNavbar.html index 38d93e2..2491aa9 100644 --- a/DocsNav/scripts/TuringNavbar.html +++ b/DocsNav/scripts/TuringNavbar.html @@ -43,6 +43,26 @@ .VPHome { padding-top: var(--navbar-height) !important; } + + /* When the rendered site is Vitepress (detected by .VPNavBar being in the + DOM), adopt Vitepress's design tokens so the TuringLang navbar tracks + the active theme (light/dark, brand colour, body font) and reads as one + piece of chrome with the Vitepress nav below it — rather than a stacked + second header with its own colour and typography. */ + html:has(.VPNavBar) { + --primary-bg: var(--vp-c-bg); + --heading-color: var(--vp-c-text-1); + --item-color: var(--vp-c-text-2); + --icon-color: var(--vp-c-text-1); + --hover-color: var(--vp-c-brand-1); + --shadow-color: var(--vp-c-divider); + --dropdown-hover-bg: var(--vp-c-default-soft); + --font-family: var(--vp-font-family-base); + } + html:has(.VPNavBar) .ext-navigation { + box-shadow: none; + border-bottom: 1px solid var(--vp-c-divider); + } /* End of DocumenterVitepress Tweaks */ /* Color and Font Variables */ From 6bb126ddf5a691ea4b8649d1c08e55ff7620f1cc Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Sun, 17 May 2026 16:13:32 +0530 Subject: [PATCH 5/6] =?UTF-8?q?DocsNav:=20fix=20Vitepress=20chrome=20stack?= =?UTF-8?q?ing=20=E2=80=94=20gap=20+=20content=20overlap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two bugs in the previous Vitepress overrides: 1. Both `.VPNav` (outer position:fixed) and `.VPNavBar` (inner position:relative inside `.VPNav`) were getting `top: var(--navbar-height)`. Relative-positioned children's `top` shifts them WITHIN their parent, so this double-offset the bar by `2 × --navbar-height` and produced a visible empty band between the TuringLang navbar and the Vitepress nav. Fix: shift only the outer `.VPNav`. 2. `.VPSidebar` and `.VPContent` were getting `padding-top: var(--navbar-height) !important`. That REPLACED Vitepress's own padding-top for its nav, so the content's top moved up by `var(--vp-nav-height) - var(--navbar-height)` — the Vitepress nav ended up floating in the middle of the page and content rendered both above and below it. Fix: - For `.VPSidebar` and `.VPLocalNav` (independently position:fixed at `top: var(--vp-nav-height)`) set `top: calc(var(--vp-nav-height) + var(--navbar-height))` so they clear both navs. - For `.VPContent` use `margin-top: var(--navbar-height)`. Margin is additive to Vitepress's existing padding-top, so the content correctly sits below both navs without removing the Vitepress nav padding. Co-Authored-By: Claude --- DocsNav/scripts/TuringNavbar.html | 34 ++++++++++++++++++------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/DocsNav/scripts/TuringNavbar.html b/DocsNav/scripts/TuringNavbar.html index 2491aa9..eeb2f6b 100644 --- a/DocsNav/scripts/TuringNavbar.html +++ b/DocsNav/scripts/TuringNavbar.html @@ -25,23 +25,29 @@ /* DocumenterVitepress CSS Overrides: Vitepress fixes its own nav and sidebar to the top of the viewport, which would overlap the TuringLang navbar inserted just inside . - Push everything Vitepress-side down by --navbar-height so the two stack - cleanly. Only fires when these Vitepress classes are present, so it - has no effect on Documenter HTML output. */ - .VPNav, - .VPNavBar, - .VPLocalNav, - .VPLocalNavOuterContainer { + Push the Vitepress-side fixed chrome down by --navbar-height so the + two stack cleanly. Only fires when these Vitepress classes are + present, so it has no effect on Documenter HTML output. */ + + /* `.VPNav` is the outer position:fixed container; its inner `.VPNavBar` + is position:relative, so shifting only the outer is correct (shifting + both would double-offset and create a gap). */ + .VPNav { top: var(--navbar-height) !important; } - .VPSidebar { - padding-top: var(--navbar-height) !important; + /* Sidebar and mobile sticky local-nav are independently fixed at + top:var(--vp-nav-height); add --navbar-height so they clear both + the TuringLang navbar and Vitepress's own nav. */ + .VPSidebar, + .VPLocalNav, + .VPLocalNavOuterContainer { + top: calc(var(--vp-nav-height, 64px) + var(--navbar-height)) !important; } - .VPContent.has-sidebar, - .VPContent.is-home, - .VPDoc, - .VPHome { - padding-top: var(--navbar-height) !important; + /* Page content already has padding-top to clear Vitepress's nav. + Add --navbar-height as a margin (additive) so it also clears + the TuringLang navbar above. */ + .VPContent { + margin-top: var(--navbar-height); } /* When the rendered site is Vitepress (detected by .VPNavBar being in the From 7fa3081c2bc0c117cc6b198d1a5cfa09dc3a02cb Mon Sep 17 00:00:00 2001 From: Shravan Goswami Date: Sun, 17 May 2026 16:27:58 +0530 Subject: [PATCH 6/6] DocsNav: use Vitepress's --vp-layout-top-height hook for stacking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the manual shift overrides for `.VPNav` / `.VPSidebar` / `.VPLocalNav` / `.VPContent` with a single rule that binds Vitepress's own `--vp-layout-top-height` variable to the TuringLang navbar height. Vitepress's default theme is authored exactly for this case: every layout-sensitive component already adds `--vp-layout-top-height` to its own offset (verified against vitepress@1.6.4 — `VPNav.vue` uses `top: var(--vp-layout-top-height, 0px)`, `VPContent.vue` uses `margin: var(--vp-layout-top-height, 0px) ...`, `VPSidebar.vue` uses `top: var(--vp-layout-top-height, 0px)`, `VPLocalNav.vue` uses `padding-top: var(--vp-layout-top-height, 0px)`, and `VPDoc.vue`'s sticky aside includes the variable in its `padding-top` calc). Using the hook fixes: - The empty band that the previous `.VPNav` + `.VPNavBar` double-shift produced. - The content / TOC clipping behind the Vitepress nav from `padding-top:var(--navbar-height) !important` replacing Vitepress's own padding. - The sidebar dropping far below the Vitepress nav because manual `calc(--vp-nav-height + --navbar-height)` over-counted Vitepress's internal padding. Co-Authored-By: Claude --- DocsNav/scripts/TuringNavbar.html | 38 ++++++++++--------------------- 1 file changed, 12 insertions(+), 26 deletions(-) diff --git a/DocsNav/scripts/TuringNavbar.html b/DocsNav/scripts/TuringNavbar.html index eeb2f6b..ccaea92 100644 --- a/DocsNav/scripts/TuringNavbar.html +++ b/DocsNav/scripts/TuringNavbar.html @@ -22,32 +22,18 @@ } /* End of Documenter.jl Tweaks */ - /* DocumenterVitepress CSS Overrides: - Vitepress fixes its own nav and sidebar to the top of the viewport, - which would overlap the TuringLang navbar inserted just inside . - Push the Vitepress-side fixed chrome down by --navbar-height so the - two stack cleanly. Only fires when these Vitepress classes are - present, so it has no effect on Documenter HTML output. */ - - /* `.VPNav` is the outer position:fixed container; its inner `.VPNavBar` - is position:relative, so shifting only the outer is correct (shifting - both would double-offset and create a gap). */ - .VPNav { - top: var(--navbar-height) !important; - } - /* Sidebar and mobile sticky local-nav are independently fixed at - top:var(--vp-nav-height); add --navbar-height so they clear both - the TuringLang navbar and Vitepress's own nav. */ - .VPSidebar, - .VPLocalNav, - .VPLocalNavOuterContainer { - top: calc(var(--vp-nav-height, 64px) + var(--navbar-height)) !important; - } - /* Page content already has padding-top to clear Vitepress's nav. - Add --navbar-height as a margin (additive) so it also clears - the TuringLang navbar above. */ - .VPContent { - margin-top: var(--navbar-height); + /* DocumenterVitepress integration: + Vitepress's default theme already exposes `--vp-layout-top-height` as + the hook for adding banner-style chrome above its own nav. Every + layout-sensitive component (`.VPNav` `top`, `.VPContent` `margin`, + `.VPSidebar` `top`, `.VPLocalNav` `padding-top`, `.VPDocAside` `top` + and TOC `padding-top`) is already authored to add this variable to + its own offset, so binding it to the TuringLang navbar height makes + Vitepress reflow itself correctly with zero further intervention. + (`:has(.VPNavBar)` scopes this to Vitepress builds; Documenter HTML + sites are untouched.) */ + html:has(.VPNavBar) { + --vp-layout-top-height: var(--navbar-height); } /* When the rendered site is Vitepress (detected by .VPNavBar being in the