feat: every project's site gets a default Contributing page - #2
Merged
Conversation
raylib-android's own docs got a hand-written CONTRIBUTING.md and a mirrored
docs/guide/contributing.md this session, and it became obvious partway
through that "how to open an issue against a jlt-commons project" is the
same answer for every project using this engine, so it belongs here, on
the same footing as base.html or 404.html, rather than copied into each
project's own docs/guide/.
- resources/content/contributing.md: the default page content (the
Clojure community etiquette guide, adapted, plus a short invitation).
- src/site/core.clj:
- discover-doc-ids now adds the engine's default-root-doc-basenames
(currently just "contributing.md") to a project's guide-dir root
group, for any name the project has not written itself. Nested
subdirectories are untouched.
- new doc-source resolves a doc-id to the project's own file if it
exists, else the engine's bundled resources/content/<doc-id> — the
override mechanism. render-all-docs now goes through it instead of a
raw slurp.
- test/site/core_test.clj: three new tests — a project with no
contributing.md gets the engine default, it lands in nav right after
index.md (a sort-order check, not just presence), and a project's own
docs/guide/contributing.md replaces the default outright.
- README.md: new "The default Contributing page" section documenting the
mechanism and its override, plus stating the general shape for any
future default page.
Verified against a real project, not just the fixture suite: built
raylib-android against this checkout and confirmed guide/contributing.html
renders, appears in nav, and raylib-android's own docs/check-site.sh still
passes (33 images, 4 guide pages, up from 2). Also ran the CI workflow's
own end-to-end demo-project build by hand, including its base-path escape
check, since this change touches the URLs every project's pages emit.
bb test: 70 tests, 153 assertions, 0 failures, 0 errors.
This was referenced Sep 7, 2026
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.
Why
Came out of a raylib-android session: it got its own
CONTRIBUTING.mdplus a mirroreddocs/guide/contributing.mdso the content would show up on its published site. Copying that into every project that uses this engine is the wrong shape, since "how to open an issue against a jlt-commons project" is the same answer everywhere. This engine already draws that line forbase.html/404.html(shared chrome vs. project content); this extends the same idea to a page.What changes
guide/contributing.htmlautomatically, right afterindex.mdin the nav, with no config and no file to write.docs/guide/contributing.md, discovered the same way any guide page is, and it replaces the default outright.discover-doc-ids+ a newdoc-source, documented in the README under "The default Contributing page"), so a future default page follows the same shape.Verification
bb test: 70 tests, 153 assertions, 0 failures, 0 errors (67 existing + 3 new, covering: default page appears with no project file, correct nav position, project's own file overrides).demo-projectbuild by hand, including its base-path-escape check, since this touches the URLs every page on every project emits.raylib-androidagainst this branch and confirmedguide/contributing.htmlrenders with the right content, shows up in nav, and raylib-android's owndocs/check-site.shstill passes (4 guide pages now, up from 2).After merge
Plan to tag a release and bump raylib-android's pinned tag in
.github/workflows/site.ymlto pick this up on its published site, then look at doing the same for other jlt-commons projects that use this engine.