Add DocumenterVitepress support to DocsDocumenter#32
Open
shravanngoswamii wants to merge 6 commits into
Open
Conversation
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 <noreply@anthropic.com>
The static HTML navbar is inserted right after <body>, 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
use-vitepressinput to theDocsDocumenteraction. When true, the deploy step usesDocumenterVitepress.deploydocs()instead ofDocumenter.deploydocs().