{"id":23624795,"url":"https://github.com/hcl-tech-software/hcl-mkdocs-build-image","last_synced_at":"2025-07-19T04:33:33.623Z","repository":{"id":194578993,"uuid":"647884155","full_name":"HCL-TECH-SOFTWARE/hcl-mkdocs-build-image","owner":"HCL-TECH-SOFTWARE","description":"COntainers we use to build HCL documentation","archived":false,"fork":false,"pushed_at":"2025-07-14T13:40:14.000Z","size":175,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-18T21:21:13.171Z","etag":null,"topics":["documentation","mkdocs","mkdocs-material"],"latest_commit_sha":null,"homepage":"https://github.com/HCL-TECH-SOFTWARE/hcl-mkdocs-build-image/issues","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HCL-TECH-SOFTWARE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-31T18:23:17.000Z","updated_at":"2025-04-03T13:08:51.000Z","dependencies_parsed_at":"2024-02-22T19:48:08.708Z","dependency_job_id":"60c06fbe-b9e3-485a-bc14-62dee0504041","html_url":"https://github.com/HCL-TECH-SOFTWARE/hcl-mkdocs-build-image","commit_stats":null,"previous_names":["hcl-tech-software/hcl-mkdocs-build-image"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HCL-TECH-SOFTWARE/hcl-mkdocs-build-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HCL-TECH-SOFTWARE%2Fhcl-mkdocs-build-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HCL-TECH-SOFTWARE%2Fhcl-mkdocs-build-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HCL-TECH-SOFTWARE%2Fhcl-mkdocs-build-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HCL-TECH-SOFTWARE%2Fhcl-mkdocs-build-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HCL-TECH-SOFTWARE","download_url":"https://codeload.github.com/HCL-TECH-SOFTWARE/hcl-mkdocs-build-image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HCL-TECH-SOFTWARE%2Fhcl-mkdocs-build-image/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265888918,"owners_count":23844531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","mkdocs","mkdocs-material"],"created_at":"2024-12-27T21:16:30.188Z","updated_at":"2025-07-19T04:33:33.596Z","avatar_url":"https://github.com/HCL-TECH-SOFTWARE.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MkDocs HCL Container image\n\n## Objective\n\nCreate and maintain a container (a.k.a. Docker) image having all [MKDocs Material](https://squidfunk.github.io/mkdocs-material/) customizations HCL Labs and friends found useful. It supports both local run and is used in the HCL internal Jenkins pipelines. It also contains the version preprocessor to generate multiple versions that differ only in the specified delta\n\n## Projects using the template\n\n- [HCL Volt MX Go](https://github.com/HCL-TECH-SOFTWARE/voltmxgo-documentation)\n- [HCL Domino REST API](https://github.com/HCL-TECH-SOFTWARE/Domino-rest-api/branches)\n\n## Multi-Version build\n\nThe image now contains our [mkdocs-preprocessor](preprocessor.md) which allows to comfortably maintain documentation versions for software version without duplicating sources.\n\n## Build result\n\nThe build creates 2 flavors:\n\n- Intel for local run\n- M1 (Apple) for local run\n\nThe resulting container is available in our [Github repository](https://github.com/HCL-TECH-SOFTWARE/domino-jnx/pkgs/container/mkdocs).\n\n## MKDocs plugins used\n\n- [mkdocs-awesome-pages-plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/)\n- [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)\n- [mike](https://github.com/jimporter/mike)\n- [mkdocs-markdownextradata-plugin](https://github.com/rosscdh/mkdocs-markdownextradata-plugin)\n- [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin)\n\n## Local building\n\nThe images are built by GitHub, so typically, you don't need to build them locally.\n\nRun `./makedocker.sh` for Intel or `./makedockerM1.sh` for Mac M1 in the project root directory. It will create the respecitve images:\n\n- For Intel: ghcr.io/hcl-tech-software/mkdocs:latest\n- For Mac M1: ghcr.io/hcl-tech-software/mkdocs:m1\n\n## Local usage\n\nWe presume you follow the convention to keep your documentation in the `/docs` directory.\nNavigate to your project root directory and run:\n\n- For Mac M1: `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs ghcr.io/hcl-tech-software/mkdocs:m1 $1 $2 $3`\n- For Intel / Linux: `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs ghcr.io/hcl-tech-software/mkdocs:latest $1 $2 $3`\n\nReplace $1, $2, $3 with valid mkdocs commands or omit them.\n\n## Command files\n\nCopy the `docs` or `docsM1` file to `~/bin` ( you have that in your path, isn't it?), and you can enjoy quick launch by typing `docs` in your project root directory.\n\n## Sample MKDocs setup file\n\nCheck the `samples` directory for `mkdocs.yml`.\n\nYMMV\n\n## mkdocs-preprocessor\n\nMake documentation versions painless with MKDocs\n\n## Problem statement\n\nDocumentation needs to cover multiple software versions. A large number of pages apply to all versions and should be maintained in a single source. Some pages exists only for some versions, some have version specific sections. Users need to able to switch between versions.\n\n## Source Directory Structure\n\n```mermaid\nstateDiagram-v2\nclassDef mutaBor fill:#f00,color:white,font-weight:bold\nclassDef fixed fill:#cccccc,color:black\n\n[*] --\u003e config.yml\n[*] --\u003e mkdocs.yml\n    [*] --\u003e docs\n    [*] --\u003e theme_override\n    docs --\u003e index.md\n    docs --\u003e .pages\n    docs --\u003e assets\n    docs --\u003e current\nclass theme_override fixed\nclass assets fixed\nclass current mutaBor\n```\n\n## Target Directory Structure\n\n```mermaid\nstateDiagram-v2\nclassDef mutaBor fill:#f00,color:white,font-weight:bold\nclassDef fixed fill:#cccccc,color:black\n    [*] --\u003e mkdocs.yml\n    [*] --\u003e docs\n    [*] --\u003e theme_override\n    docs --\u003e index.md\n    docs --\u003e .pages\n    docs --\u003e assets\n    docs --\u003e Versions\n    state Versions {\n    [*] --\u003e v1\n    [*] --\u003e v2\n    [*] --\u003e v3\n    [*] --\u003e latest\n    }\nclass theme_override fixed\nclass assets fixed\nclass latest fixed\nclass v1 mutaBor\nclass v2 mutaBor\nclass v3 mutaBor\n```\n\n## Front Matter\n\nOn top of each markdown document generated in one of the version paths you will find this front-matter (plus eventual existing front matter)\n\n```yaml\nthis_version: v1\nall_versions:\n  - v1\n  - v2\n  - v3\nisLatest: false\n```\n\n## Configuration\n\nThe pre-processor needs a `yaml` file to configure its run:\n\n```yaml\nsource: /source # directory with source files\ntarget: /target # directory for output, files will be overwritten here\nall_versions: # list of versions to generate, simple or semantic\n  - v1\n  - v2\ngenerate_redirects: true # Should redirect files be created in directory without version number\ngenerate_latest: true # Should there be a directory `/latest` for indexing use\n```\n\n- Version can be simple `v1`, or semantic `v1.1` or `v1.0.2`\n\n## How it works\n\n- scans the source sub-directory with the name `current` for files and copies them to the version directories\n- on copy markdown files are inspected for front-matter to determine what versions will have that page\n- the front-matter gets updated to reflect version specific info\n- if a file changes between versions, we use file name versioning. so `info.md`, `info.v1.md` and `info.v2.md` are considered the same file for different versions\n- The first version a file appears is determined by the file name `index.md` or `index.v1.md` will be in all versions. `demo.v4.1.md` will only appear in version 4.1 and higher\n- You can limit the versions a page will appear using front-matter:\n\n  ```yaml\n  max_version: v2\n  ```\n\n  will only appear in v1 and v2\n\n- `.pages` files are handled similarly `v3.pages` will replace `.pages` in v3 onwards\n\n## Caveats\n\n- You want to use the `awesome-pages` plugin to make use of `.pages` navigation structure\n- for the automatic redirect, you must disable thw `navigation.instant` feature. It is not compatible with the redirect meta statement\n- you need a template `versionredirect.html` like in the `theme_overrides` direcory in this repo\n\n## Docker use\n\nPull the version matching your hardware\n\n```bash\n# Intel / Amd 64Bit\ndocker pull ghcr.io/hcl-tech-software/mkdocs:latest\n# Arm 64 Bit (e.g M1/M2/M3 macOS)\ndocker pull ghcr.io/hcl-tech-software/mkdocs:M1\n```\n\n### Map the directories\n\n- source: directory location where your `mkdocs.yml` and `docs` can be found\n- docs: output directory for the transformed content\n- site: destination of the final rendered site\n\n### Launch samples\n\nThe following section shows options to launch the image with options\n\n#### Standard edit, no version handling\n\n```bash\n# Your current directory has regular mkdocs files\ndocker run --rm -it -p 8000:8000 \\\n           -v ${PWD}:/docs \\\n           docker.qs.hcllabs.net/hclcom/mkdocs\n```\n\n#### Version preprocessing only\n\n```bash\n# Your current directory has mkdocs to be preprocessed\n# and the result outputs to target\ndocker run --rm -it -p 8000:8000 \\\n           -v ${PWD}/target:/docs \\\n           -v ${PWD}/source:/source \\\n           docker.qs.hcllabs.net/hclcom/mkdocs versions\n```\n\n#### Preprocess \u0026 Edit\n\n```bash\n# Your current directory has mkdocs to be preprocessed\n# and the result outputs to target\ndocker run --rm -it -p 8000:8000 \\\n           -v ${PWD}/target:/docs \\\n           -v ${PWD}/source:/source \\\n           docker.qs.hcllabs.net/hclcom/mkdocs versions watch\n```\n\n### Preprocess and Render (e.g. in GitHub Action)\n\n```bash\n# Your current directory has mkdocs to be preprocessed\n# and the result outputs to target\ndocker run --rm -it -p 8000:8000 \\\n           -v ${PWD}/target:/docs \\\n           -v ${PWD}/source:/source \\\n           -v ${PWD}/site:/site \\\n           docker.qs.hcllabs.net/hclcom/mkdocs site\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcl-tech-software%2Fhcl-mkdocs-build-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcl-tech-software%2Fhcl-mkdocs-build-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcl-tech-software%2Fhcl-mkdocs-build-image/lists"}