Skip to content

Build the site with Docspire, and highlight with Prism v2 at build time - #47

Draft
DmitrySharabin wants to merge 10 commits into
v2from
docspire-migration
Draft

Build the site with Docspire, and highlight with Prism v2 at build time#47
DmitrySharabin wants to merge 10 commits into
v2from
docspire-migration

Conversation

@DmitrySharabin

@DmitrySharabin DmitrySharabin commented Sep 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Member 
Build the site with Docspire                       content under docs/, plugin pages, redirects
Restore the brand look                             brand.css: what Docspire's theme lacks
Highlight with Prism v2 at build time              fences via markdown-it; the rest in the browser
Shift headings under the page title at build time  headingOffset: 1
Split the landing page into sections of the site   /start/ /features/ /supported-languages/ /community/
Port the FAQ token browser to Prism v2
Put back the “↑ Back to top” links
Put the marked-up examples in code-blocks          <code class="language-html"> on /start/
Keep line numbers beside their lines               line-height and font on <pre> and <code>
Load a page's languages before Prism highlights it one pass, so plugins see the code once
  • Pages move from /faq.html to /faq/. /index.html redirects to /start/, so old links to the home page's usage sections keep their fragment.
  • Redirects live in netlify.toml: since Docspire 0.0.4 runs nudeps before the build, a built _redirects replaces the alias rules nudeps writes there, and Docspire's own stylesheet 404s.
  • The build highlights only fences. Code written as HTML, inline code, and code that inherits its language stay with Prism in the browser, on the pages that load it.

Not done: the theme switcher has no place in Docspire's layout yet. Getting started still describes v1 (require('prismjs'), prismjs@v1.x CDN links). The toolbar, jsonp-highlight and filter-highlight-all demos call v1 plugin APIs and throw, previewers only show in blocks with data-previewers (its isDisabled() inverts the v1 check), and the command-line README's data-continuation-str="\" fence breaks markdown-it-attrs. All need fixes in the Prism repo. Edit links point at main, which has these files only once v2 lands there.

File + −
package-lock.json 1454 566
assets/style.css 0 753
assets/styles/brand.css 493 0
docs/extending.md (moved) 167 171
README.md 0 198
docspire.config.js 112 0
docs/start.md 94 0
_layouts/page.njk 0 90
docs/index.md 86 0
_build/eleventy.js 0 72
_data/eleventyComputed.js 0 56
_build/copy-plugins.mjs 0 34
docs/features.md 29 0
netlify.toml 28 0
docs/community.md 27 0
docs/examples.md (moved) 23 4
docs/assets/faq.js (moved) 13 11
_layouts/home.njk 0 23
docs/assets/examples.js (moved) 11 11
docs/faq.md (moved) 10 10
_redirects.njk 0 18
docs/plugins/plugins.11tydata.js 18 0
docs/supported-languages.md 18 0
docs/plugins.md 17 0
_build/postinstall.mjs 5 11
_build/filters.js 1 13
docs/download.njk (moved) 7 7
.gitignore 6 6
package.json 4 7
typedoc.json 4 7
docs/tokens.md (moved) 3 6
templates/page-title.njk 8 0
_build/highlight.js 6 0
docs/test.md (moved) 3 3
docs/assets/prism.js 5 0
README.json 0 4
data/prism.js 4 0
docs/known-failures.md (moved) 2 2
docs/assets/test-drive.js (moved) 2 1
docs/test-suite.md (moved) 1 2
templates/resources.njk 3 0
docs/benchmark.md (moved) 0 2
docs/assets/download.js (moved) 1 0

Blank and comment lines not counted. The 294 example files under docs/examples/ moved unchanged.

🤖 Generated with Claude Code

DmitrySharabin and others added 7 commits September 23, 2026 00:59
@DmitrySharabin @claude
Build the site with Docspire
12269bb 
The pages move under docs/, Docspire's input directory, and its layouts,
navigation, page outline and code-blocks replace the hand-rolled 11ty setup.

- Prism's catalog is plain global data (data/prism.js), read by the download,
  examples and FAQ pages.
- postinstall clones Prism v2 into .prism, not node_modules/prismjs: Docspire's
  markdown-it-prism needs the v1 package there. The plugin READMEs it copies are
  pages of their own, listed in the sidebar, with edit links into the Prism repo.
- A plugin page loads the site's Prism first, then the plugin, then its own
  demo, from the `resources` its README lists. A content.end slot renders them.
- Prism in the browser reads a page's `body_classes` off <body>, and brand.css
  its page-specific rules off `data-inputpath`.
- netlify.toml sends themes, languages and plugin files to the v2 build. A file
  the site has wins, so one rule per URL shape does. The rules are not in
  _redirects, because on Netlify nudeps writes its own rules to that file.
- typedoc writes the API docs into _site/api.
- Links follow the new /page/ URLs, and point at /api/ instead of the v1 docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Restore the brand look
4979bf1 
brand.css keeps what Docspire's theme does not already cover: the Questrial and
Rockwell faces, the logo on a dark ground, headings at normal weight, the used-by
logos, the language and plugin lists, and the download, examples, test drive,
tokens and known-failures widgets. The download page's categories open at h2,
under the page title.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Highlight with Prism v2 at build time
402d06d 
markdown-it-prism highlights with Prism v1, and the site documents v2. Fences go
through a v2 instance with every language loaded instead, via markdown-it's
`highlight` option. What would re-create Prism's own rules stays with Prism in
the browser: code written as HTML, inline code, and code that inherits its
language from a <section> or the page.

- A fence's attributes go on the <pre>, where Prism's plugins read them, as the
  old site's renderer did.
- code-block reads the language off the <pre>, so the class on a <code> is
  copied up.
- A whole file that file-highlight fetches scrolls inside a block 30em tall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Shift headings under the page title at build time
807919c 
The layout titles every page with an h1, and the pages, like the plugin READMEs
from the Prism repo, open their sections at #. A markdown-it rule moves every
heading down by the site's `headingOffset` of 1, so the Markdown keeps the
levels it was written with.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Split the landing page into sections of the site
b9c5303 
The home page carried the whole manual. It now keeps what a landing page is for,
as on nudeps.dev: a hero whose first action is Get started, feature cards that
link to where each feature is explained, a three-step quick start, the sites
that use Prism, and the credits. It loads no Prism in the browser.

The rest moved, unchanged:
- Basic usage and its sections → /start/ (Getting started, first in the sidebar)
- Full list of features, Limitations → /features/
- Supported languages → /supported-languages/, clear of the /languages/ redirect
- Third-party definitions and tutorials → /community/
- The four whole-file examples → /examples/, each in a code-block
The plugin list left the page too, since /plugins/ has it.

Links into the old sections still arrive as /index.html#basic-usage-cdn, from the
plugin READMEs among others. /index.html redirects to /start/, and the browser
keeps the fragment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Port the FAQ token browser to Prism v2
a9e6c6d 
Prism.components is gone: languages live in Prism.languageRegistry, a grammar is
the language's resolvedGrammar, and loading one is Prism.loadLanguage(). The
<select> also needs a blank line before it, or markdown-it treats it as inline
HTML and closes it before its 303 options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Put back the “↑ Back to top” links
02a0fe1 
`back_to_top` was front matter with nothing reading it. A content transform
appends the link to each section of a page that sets it. It points at #top, the
fragment HTML reserves for the top of the document.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DmitrySharabin and others added 3 commits September 23, 2026 01:11
@DmitrySharabin @claude
Put the marked-up examples in code-blocks
5a8acdc 
The two Getting started examples with <mark>s are written as HTML, and took their
language from the section around them. code-block only wraps a <pre> whose
language the build can see, so their <code> now names it, as a fence does.
Prism and keep-markup still highlight them in the browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Keep line numbers beside their lines
bd69249 
Line numbers are rows beside the code, so a line of code must be exactly as tall
as a row. Nothing set a line height, and the <code> fell back to the browser's
plain monospace instead of the block's font. On a phone, code lines drawn partly
in a fallback font grew taller, and the numbers fell behind a little more with
every line. Prism's own themes set both, as brand.css now does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DmitrySharabin @claude
Load a page's languages before Prism highlights it
36f0d19 
In v2 a language file only exports its grammar, so the languages a plugin README
loads with a <script> register nothing. Prism highlighted each block without
its grammar, then again when the autoloader brought it. command-line's
data-filter-output strips its prefix on the first pass, so the second found no
output lines. The site's Prism now loads the language of every <code> before it
highlights, along with markup, css, clike and javascript, which v1's bundle
shipped and data-uri-highlight nests: the SVG inside a data URI is highlighted
again.

The autoloader's srcPath went to its plugin definition, not the instance, and
did nothing. It is gone: the autoloader finds the languages next to itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DmitrySharabin