Build this site with the shared docs-engine - #1
Merged
Merged
Conversation
The generator lived here, as a trimmed port of a private single-author
engine. It has since been extracted to jlt-commons/docs-engine and
generalized to serve every project site in the organization, so keeping a
second copy here means a markdown fix has to land twice and the two
drift in between.
What leaves: src/, test/, and the engine's own templates and static
assets. What stays is what belongs to this site — its pages, its
homepage template, its mark, and now docs/site.edn for the configuration
that used to be src/site/config.clj.
Content moves to the engine's conventions: content/guide -> docs/guide,
and the mark to docs/img, copied into the build by :asset-dirs rather
than by living among the engine's own static files. bb.edn keeps only
site:build / site:serve / site:clean, which shell into an engine
checkout for local preview and print the clone command when they cannot
find one. CI checks the engine out itself, pinned to v0.2.0.
Verified against the live build rather than by inspection: the output is
byte-identical to what this repo produced before, except for blank lines
left by a now-false {% if mermaid %} and three added files (.nojekyll
and the mermaid bundle, which ships but is never referenced here).
`diff -Bw` across all four pages is clean.
The engine loads mermaid only on pages that have a diagram, as of
v0.2.0. This site has none, so it gained nothing but the vendored file,
and the build now checks the bundle stays unreferenced — a regression in
that gating would otherwise add 3.4 MB to every page here silently.
The README's claim that mermaid is unsupported is no longer true and has
been rewritten along with the build instructions.
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.
The generator lived in this repo as a trimmed port of a private
single-author engine. It has since been extracted to
jlt-commons/docs-engine and
generalized to serve every project site in the organization. Keeping a second
copy here means a markdown fix lands twice, and the two drift in between.
What changes
src/,test/docs/guide/— the pagesbase,docs,404)docs/templates/home.html— this site's own homepagedocs/img/mark.svg— this site's own marksrc/site/config.cljdocs/site.edn, replacing itcontent/guide/moves todocs/guide/and the mark todocs/img/, copied intothe build by
:asset-dirsrather than living among the engine's own staticfiles.
bb.ednkeeps onlysite:build/site:serve/site:clean, whichshell into an engine checkout for local preview and print the clone command when
they cannot find one. CI checks the engine out itself, pinned to
v0.2.0.This site is live, so the output was diffed, not eyeballed
Built the site before the change, kept it, then diffed against the build after:
.nojekylland the two mermaid vendorfiles.
{% if mermaid %}.diff -Bwis clean across all four pages.One regression this would have shipped
The engine loaded the mermaid bundle unconditionally. This site has no diagrams
at all, so adopting the engine as it stood would have added 3.4 MB to every
page — roughly 450x the weight of the page itself — for a feature it does not
use.
Fixed in the engine first (
v0.2.0): detection is now per page, and the site canoverride it in either direction with
:mermaidinsite.edn. This build nowchecks the bundle stays unreferenced here, so a regression in that gating fails
the build rather than quietly costing every reader 3.4 MB. Adding a diagram to
this site means updating that check, deliberately.
Also
The README claimed mermaid was unsupported. That is no longer true, and it has
been rewritten along with the build instructions.