Skip to content

About

Source of contextgeneric.dev, the website and documentation of Context-Generic Programming (CGP), which brings pluggable trait implementations to Rust.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Deploy to GitHub Pages Test deployment License: Apache-2.0 for code Content: CC BY-SA 4.0 Node 24+

The CGP website: contextgeneric.dev

The public documentation site for Context-Generic Programming (CGP), published at contextgeneric.dev.

The site is a stock Docusaurus installation: the quickstart, the tutorials, the concepts, the construct reference, the comparisons, the project pages, the cargo-cgp guide, the AI section, and the blog. It is deliberately unmodified, without plugins or custom React beyond the landing page, so a contributor's work is almost entirely writing Markdown.

Install

npm ci

The repository carries package-lock.json, and CI installs with npm ci, so use npm rather than another package manager. Node 24 or newer is required. CI runs the version .nvmrc pins, and nvm use selects the same one locally.

Local development

npm start

This starts a local development server and opens a browser window. Most changes are reflected live without restarting the server.

Build

npm run build

This generates the static site into build/, which any static host can serve. The build fails on a broken internal link, because onBrokenLinks is set to throw, so a moved page needs every reference fixed in the same change.

The social card, the image a shared link to the site shows, is static/img/social-card.jpg, rendered from the hero illustration, the project's name, and its tag line. Regenerate it after changing either with python3 scripts/social-card/make.py, which needs google-chrome and ImageMagick, and commit the result.

Theme

The site's colours are tokens in src/css/custom.css, defined once for each theme, with the code colours in src/prism/themes.ts; page styles use the tokens rather than hex colours. After changing a colour, run the contrast check, which needs only Python 3 and exits non-zero when a pair falls below WCAG AA:

python3 scripts/theme/contrast.py

The heading and code fonts are self-hosted under static/fonts/, and scripts/fonts/README.md gives the commands that cut them.

Deployment

The site deploys from main through GitHub Pages, using the workflow in .github/workflows/deploy.yaml: a push to main builds the site and publishes it. Every other branch and every pull request runs the same build through .github/workflows/test-deploy.yaml without deploying, and that workflow also runs the example-code snippet tests.

Search engines

Search engines learn about the site from its sitemap, which Docusaurus generates at /sitemap.xml and static/robots.txt names for every crawler, and Google also reads it through Search Console. Bing and the engines that share its index can be told about changed pages straight away through IndexNow, and scripts/indexnow/submit.py sends those notices.

IndexNow checks that a submission comes from the site's owner by fetching a key file from the site. That file is static/251047bc35e2154870673d415006ae6e.txt, whose name and only content are the key. It looks like a stray file, but it has to stay deployed, and the script refuses to send anything while the live copy is missing or differs.

After a deploy that changes pages, run the script from the repository's root with the URLs of those pages:

python3 scripts/indexnow/submit.py https://contextgeneric.dev/docs/quickstart/

Each URL must be on https://contextgeneric.dev, in the trailing-slash form the sitemap uses. --dry-run prints what would be sent and whether the live key file matches, without sending anything. --all sends every URL in the live sitemap together with the redirect stubs under static/. That suits only a relaunch or a move of many pages, because IndexNow asks sites to submit just the pages that changed.

Writing a page

Read the knowledge base's website section for the page you are about to touch before writing. It records, for every page the site publishes, what that page says, which knowledge-base documents own its content, and how far its code has drifted from the current release. The writing guides say how each kind of page should be written.

The site documents cgp v0.8.0 and cargo-cgp v0.1.0. Verify every snippet against the current release, the cgp source, or its tests, and prefer code already verified in the knowledge base's examples/ directory. The example-code crate in this repository compiles the snippets the pages show, so a page cannot drift from the library without a failing test.

Links

A published page never links into the knowledge base, apart from the two hand-written exceptions the knowledge base's website rules set: docs/ai/disclaimer.md and the pages under docs/ai/knowledge-base/. The published skill pages under docs/ai/skills/ may cite the knowledge base by deep GitHub URL, because nobody hand-writes them.

Link only public resources: other pages on this site, the cgp repository and its siblings, docs.rs, crates.io, and ordinary external sources.

License

The repository's source code is licensed under the Apache License, Version 2.0, the same as cgp. The published pages are licensed under CC BY-SA 4.0, as the site's footer states.

Related repositories

The CGP knowledge base lists every repository in the ecosystem and the revision of each to read.

About

Source of contextgeneric.dev, the website and documentation of Context-Generic Programming (CGP), which brings pluggable trait implementations to Rust.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages