docs/developer_guide/documentation.md
We want documentation at docs.rendercv.com, a proper website with navigation, search, theming, and interactive features.
What is a website? A collection of HTML, CSS, and JavaScript files. Browsers download these files and render them as the pages you see. To have a website, you need:
docs.rendercv.com) pointing to that serverThe problem: We don't want to develop a web app (writing HTML/CSS/JavaScript). We just want to put some content online.
What if we could write content in Markdown and use some software to automatically generate HTML/CSS/JavaScript files from it?
The solution: MkDocs with Material theme. You write Markdown in docs/, MkDocs generates HTML/CSS/JavaScript, and GitHub Pages hosts it at docs.rendercv.com.
Tools like MkDocs exist because documentation sites follow a stable, well-understood pattern. They aren’t open-ended web applications with unique interfaces or behaviors; they’re a specific kind of website with predictable needs: structured pages, cross-page navigation, search, consistent styling, and readable content.
Once a pattern becomes that well defined, entire ecosystems form around it. Just as you reach for Python rather than designing a new programming language, you reach for MkDocs rather than hand-assembling HTML, CSS, and JavaScript files for a documentation site.
mkdocs.yamlmkdocs.yaml controls how MkDocs builds the website:
MkDocs plugins extend functionality beyond Markdown → HTML conversion.
mkdocstrings: API ReferenceGenerates the API reference from Python docstrings. The entire API Reference section is auto-generated from src/rendercv/.
mkdocs-macros-plugin: Dynamic ContentLets you inject code-generated values into Markdown. docs/docs_templating.py runs during the build. It imports values directly from RenderCV's code and exposes them as variables. It's heavily used in YAML Input Structure: cv Field page.
The YAML Input Structure: cv Field page shows example images of each entry type rendered in each theme.
These are auto-generated PNG images. Run just update-entry-figures to regenerate them from docs/user_guide/sample_entries.yaml.
just serve-docs
Starts a local server at http://127.0.0.1:8000 with live reload. Edit Markdown files and see changes instantly.
just build-docs
Generates the final website in the site/ directory. Mainly used by GitHub workflows for final deployment (see GitHub Workflows).
Every push to main triggers automatic deployment.
The workflow (.github/workflows/deploy-docs.yaml):
mainuv and justjust build-docs to generate the websitesite/ directory as an artifactdocs.rendercv.comSee the MkDocs Material documentation for more information.