feat(docs): migrate documentation site from Material for MkDocs to Zensical

.github/workflows/build.yml

@@ -724,7 +724,7 @@ jobs:
           name: docs
           path: tmp/docs/
 
-      - name: Build mkdocs
+      - name: Build docs site
         run: pnpm mkdocs build --no-build
 
   test-e2e:
@@ -908,7 +908,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       # Rebuild the docs site to make sure that we have the version specified in the JSON Schema and page footer
-      - name: Build mkdocs for Renovate ${{ steps.latest_release.outputs.release_tag }}
+      - name: Build docs site for Renovate ${{ steps.latest_release.outputs.release_tag }}
         run: pnpm mkdocs build --version ${{ steps.latest_release.outputs.release_tag }}
         env:
           GITHUB_TOKEN: ${{ github.token }}

docs/development/local-development.md

@@ -206,7 +206,7 @@ To get real-time oxlint diagnostics, install the extension for your editor:
 
 ## Documentation
 
-We use [MkDocs](https://www.mkdocs.org) to generate the documentation.
+We use [Zensical](https://zensical.org/) to generate the documentation.
 To install the required dependency, use `pdm install`.
 You can run `pnpm build:docs` to generate the docs.
 Then use `pnpm mkdocs serve` to preview the documentation locally.

docs/usage/about-us.md

@@ -44,8 +44,8 @@ Some features made a lot of people happy, and efficient!
 - [@RahulGautamSingh](https://github.com/RahulGautamSingh) refactored a lot of code and worked on performance improvements like reduced cloning during updates and onboarding
 - [@Gabriel-Ladzaretti](https://github.com/Gabriel-Ladzaretti) S3 repo cache, child process refactoring, others
 - [@not7cd](https://github.com/not7cd) improved the `pip-compile` manager
-- [@squidfunk](https://github.com/squidfunk) for creating and maintaining the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework, that we use to build our docs, and for helping us with problems with the framework, or our docs
-- [The MkDocs project](https://www.mkdocs.org/) for making the static site generator, that we use to build our docs
+- [@squidfunk](https://github.com/squidfunk) for creating and maintaining the [Zensical](https://zensical.org/) framework, that we use to build our docs, and for helping us with problems with the framework, or our docs
+- [The Zensical project](https://zensical.org/) for making the static site generator, that we use to build our docs
 
 ## Renovate development
 
@@ -64,4 +64,4 @@ If you need more assistance than what this project offers, you have two options:
 The Renovate docs are built from Markdown files in our [`renovatebot/renovate` repository](https://github.com/renovatebot/renovate).
 Most of the source files can be found in the [`docs/usage/` directory](https://github.com/renovatebot/renovate/tree/main/docs/usage).
 
-We use [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to build our docs.
+We use [Zensical](https://zensical.org/) to build our docs.

pyproject.toml

@@ -1,7 +1,6 @@
 [project]
 dependencies = [
-  "mkdocs-material==9.7.2",
-  "mkdocs-awesome-pages-plugin==2.10.1",
+  "zensical==0.0.23",
 ]
 requires-python = ">=3.11"
 

tools/generate-docs.ts

@@ -10,11 +10,11 @@ process.on('unhandledRejection', (err) => {
 
 const program = new Command('pnpm build:docs')
   .description('Generate docs')
-  .option('--mkdocs', 'generate docs for mkdocs')
+  .option('--mkdocs', 'generate docs for zensical')
   .option('--version <version>', 'the current version of the Renovate CLI')
   .action(async (opts) => {
     if (opts.mkdocs) {
-      logger.info('Generating for mkdocs');
+      logger.info('Generating for zensical');
       await generateDocs('tools/mkdocs', false, opts.version);
     } else {
       logger.info('Generating docs for testing');

tools/mkdocs.ts

@@ -11,18 +11,18 @@ process.on('unhandledRejection', (err) => {
   process.exit(-1);
 });
 
-const program = new Command('pnpm mkdocs').description('Run mkdocs');
+const program = new Command('pnpm mkdocs').description('Run zensical');
 
 program
   .command('build', { isDefault: true })
-  .description('Build mkdocs')
+  .description('Build zensical')
   .option('--version <version>', 'the current version of the Renovate CLI')
   .option('--no-build', 'do not build docs from source')
   .option('--no-strict', 'do not build in strict mode')
   .action(async (opts) => {
     await prepareDocs(opts);
-    logger.info('* running mkdocs build');
-    const args = ['run', 'mkdocs', 'build'];
+    logger.info('* running zensical build');
+    const args = ['run', 'zensical', 'build'];
     if (opts.strict) {
       args.push('--strict');
     }
@@ -39,14 +39,14 @@ program
 
 program
   .command('serve')
-  .description('serve mkdocs')
+  .description('serve zensical')
   .option('--no-build', 'do not build docs from source')
   .option('--no-strict', 'do not build in strict mode')
   .action(async (opts) => {
     await prepareDocs(opts);
     logger.info('serving docs');
-    logger.info('* running mkdocs serve');
-    const args = ['run', 'mkdocs', 'serve'];
+    logger.info('* running zensical serve');
+    const args = ['run', 'zensical', 'serve'];
     if (opts.strict) {
       args.push('--strict');
     }

tools/mkdocs/includes/abbreviations.md

@@ -1,5 +1,5 @@
-<!-- Material for MkDocs shows a tooltip when you hover over any abbreviation in this list. -->
-<!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary -->
+<!-- Zensical shows a tooltip when you hover over any abbreviation in this list. -->
+<!-- https://zensical.org/docs/authoring/tooltips/ -->
 
 <!-- Please keep this list sorted from A-Z. -->
 

tools/mkdocs/overrides/main.html

@@ -1,16 +1,16 @@
 {% extends "base.html" %}
 
 <!-- This file has the content for our announcement bar. -->
-<!-- https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#announcement-bar -->
-<!-- https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks -->
+<!-- https://zensical.org/docs/setup/header/#announcement-bar -->
+<!-- https://zensical.org/docs/customization/#extending-the-theme -->
 
 <!-- To disable the announcement bar: -->
-<!-- 1. Open the tools/mkdocs/mkdocs.yml file. -->
-<!-- 2. Comment out the `theme.custom_dir` entry. -->
+<!-- 1. Open the tools/mkdocs/zensical.toml file. -->
+<!-- 2. Remove "announce.dismiss" from the theme.features list. -->
 
 <!-- To enable the announcement bar: -->
-<!-- 1. Open the tools/mkdocs/mkdocs.yml file. -->
-<!-- 2. Make sure the `theme.custom_dir` entry is plain code. -->
+<!-- 1. Open the tools/mkdocs/zensical.toml file. -->
+<!-- 2. Add "announce.dismiss" to the theme.features list. -->
 
 
 {% block announce %}

tools/mkdocs/overrides/partials/copyright.html

@@ -9,11 +9,11 @@
   </p>
   {% endif %} {% if not config.extra.generator == false %} Made with
   <a
-    href="https://squidfunk.github.io/mkdocs-material/"
+    href="https://zensical.org/"
     target="_blank"
     rel="noopener"
   >
-    Material for MkDocs
+    Zensical
   </a>
   {% endif %}
 </div>