├── .github ├── dependabot.yml └── workflows │ ├── ci.yml │ ├── post-deploy-test.yml │ └── test.yml ├── .gitignore ├── .vscode └── settings.json ├── Dockerfile ├── LICENSE ├── README.md ├── action.yml ├── config ├── arithmatex.config.js ├── mkdocs.yml ├── requirements.txt ├── theme.404.html └── theme.main.html ├── local.sh ├── script └── makedocs.sh └── test ├── test_on_ghcr └── action.yml ├── test_on_hub └── action.yml └── test_on_self └── action.yml /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | # Maintain dependencies for GitHub Actions 4 | - package-ecosystem: "github-actions" 5 | directory: "/" 6 | schedule: 7 | interval: "weekly" 8 | labels: 9 | - "CI/CD" 10 | - "dependency" 11 | - "bot" 12 | target-branch: "master" 13 | 14 | # Maintain dependencies for Pip 15 | - package-ecosystem: "pip" 16 | directory: "config/" 17 | schedule: 18 | interval: "weekly" 19 | labels: 20 | - "python" 21 | - "dependency" 22 | - "bot" 23 | target-branch: "master" 24 | 25 | - package-ecosystem: "docker" 26 | directory: "/" 27 | schedule: 28 | interval: "monthly" 29 | labels: 30 | - "docker" 31 | - "dependency" 32 | - "bot" 33 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI/CD 2 | on: 3 | pull_request: 4 | push: 5 | branches: 6 | - "*" 7 | tags: 8 | - "*" 9 | schedule: 10 | - cron: "0 8 1 * *" 11 | 12 | 13 | jobs: 14 | checks: 15 | runs-on: ubuntu-latest 16 | name: Check pushed paths 17 | outputs: 18 | should-release: ${{ steps.semver-checkout.outputs.should-release == 'true' && github.event_name != 'pull_request' }} 19 | version: ${{ steps.semver-checkout.outputs.version }} 20 | is-prerelease: ${{ steps.semver-checkout.outputs.is-github-prerelease }} 21 | doc-updated: ${{ steps.filter.outputs.md }} 22 | steps: 23 | - id: semver-checkout 24 | name: Checkout 25 | uses: EasyDesk/action-semver-checkout@v1 26 | - id: filter 27 | uses: dorny/paths-filter@v3 28 | if: github.event_name != 'schedule' 29 | with: 30 | filters: | 31 | md: 32 | - '**/*.md' 33 | - '*.md' 34 | test: 35 | name: Tests on self 36 | uses: ./.github/workflows/test.yml 37 | 38 | release: 39 | name: GitHub Release Job 40 | if: ${{ needs.checks.outputs.should-release == 'true' }} 41 | needs: 42 | - checks 43 | - test 44 | runs-on: ubuntu-20.04 45 | concurrency: release 46 | permissions: 47 | contents: write 48 | steps: 49 | - uses: EasyDesk/action-semver-release@v1 50 | with: 51 | version: ${{ needs.checks.outputs.version }} 52 | prerelease: ${{ needs.checks.outputs.is-prerelease }} 53 | 54 | push-to-registries: 55 | name: Push Docker image to multiple registries 56 | runs-on: ubuntu-latest 57 | if: github.event_name != 'pull_request' 58 | needs: 59 | - test 60 | - checks 61 | permissions: 62 | packages: write 63 | contents: write 64 | concurrency: registries 65 | steps: 66 | - name: Check out the repo 67 | uses: actions/checkout@v4 68 | - name: Docker meta 69 | id: meta 70 | uses: docker/metadata-action@v5 71 | with: 72 | # list of Docker images to use as base name for tags 73 | images: | 74 | deloo/markdown-docs 75 | ghcr.io/ldeluigi/markdown-docs 76 | # generate Docker tags based on the following events/attributes 77 | tags: | 78 | type=edge 79 | type=schedule,pattern=nightly 80 | type=schedule,pattern=auto-{{date 'YYYYMMDDHHmm'}} 81 | type=semver,pattern={{version}},enable=${{ needs.checks.outputs.should-release == 'true' }} 82 | type=semver,pattern={{major}}.{{minor}},enable=${{ needs.checks.outputs.should-release == 'true' }} 83 | type=semver,pattern={{major}},enable=${{ needs.checks.outputs.should-release == 'true' && !startsWith(github.ref, 'refs/tags/v0.') }} 84 | labels: | 85 | maintainer=ldeluigi 86 | org.opencontainers.image.title=Markdown Docs 87 | org.opencontainers.image.description=Contains scripts to generate documentation from markdown and PlantUML. 88 | - name: Set up Docker Buildx 89 | uses: docker/setup-buildx-action@v3 90 | - name: Login to DockerHub 91 | uses: docker/login-action@v3 92 | with: 93 | username: ${{ secrets.DOCKER_USERNAME }} 94 | password: ${{ secrets.DOCKER_PASSWORD }} 95 | - name: Login to GitHub Container Registry 96 | uses: docker/login-action@v3 97 | with: 98 | registry: ghcr.io 99 | username: ${{ github.repository_owner }} 100 | password: ${{ secrets.GITHUB_TOKEN }} 101 | - name: Build and push 102 | uses: docker/build-push-action@v6 103 | with: 104 | context: . 105 | file: Dockerfile 106 | push: true 107 | tags: ${{ steps.meta.outputs.tags }} 108 | labels: ${{ steps.meta.outputs.labels }} 109 | 110 | post-deploy-test: 111 | name: Post-deploy test 112 | needs: [push-to-registries] 113 | uses: ./.github/workflows/post-deploy-test.yml 114 | 115 | update-gh-pages: 116 | name: Generate and upload new GitHub Pages 117 | runs-on: ubuntu-latest 118 | needs: 119 | - release 120 | - push-to-registries 121 | concurrency: github-pages 122 | steps: 123 | - name: Check out the repo 124 | uses: actions/checkout@v4 125 | with: 126 | fetch-depth: 0 127 | - name: Run action 128 | uses: ./ 129 | with: 130 | src: . 131 | dst: ./result 132 | icon: file-document-edit 133 | - name: Deploy GH Pages 134 | uses: peaceiris/actions-gh-pages@v4 135 | with: 136 | github_token: ${{ secrets.GITHUB_TOKEN }} 137 | publish_dir: ./result 138 | -------------------------------------------------------------------------------- /.github/workflows/post-deploy-test.yml: -------------------------------------------------------------------------------- 1 | name: Post-deploy Test 2 | 3 | on: 4 | workflow_call: 5 | push: 6 | paths: 7 | - ".github/workflows/post-deploy-test.yml" 8 | tags-ignore: 9 | - "*" 10 | 11 | jobs: 12 | test1: 13 | name: Test on GitHub Container Registry 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v4 17 | with: 18 | fetch-depth: 0 19 | - name: Run action 20 | uses: ./test/test_on_ghcr/ 21 | with: 22 | src: . 23 | dst: ./result 24 | language: en 25 | primary-color: black 26 | secondary-color: red 27 | hide-repository: false 28 | title: Title 29 | - name: Verify result 30 | run: | 31 | test ! -z "$(ls -A ./result)" 32 | test2: 33 | name: Test on Docker Hub 34 | runs-on: ubuntu-latest 35 | steps: 36 | - uses: actions/checkout@v4 37 | with: 38 | fetch-depth: 0 39 | - name: Run action 40 | uses: ./test/test_on_hub/ 41 | with: 42 | src: . 43 | dst: ./result 44 | language: en 45 | primary-color: black 46 | secondary-color: red 47 | hide-repository: false 48 | title: Title 49 | - name: Verify result 50 | run: | 51 | test ! -z "$(ls -A ./result)" 52 | 53 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: Test 2 | on: 3 | workflow_call: 4 | 5 | jobs: 6 | test1: 7 | runs-on: ubuntu-latest 8 | strategy: 9 | fail-fast: false 10 | matrix: 11 | hide-repository: [true, false] 12 | title: ['', 'Ok_?@ sadadsa 😁'] 13 | steps: 14 | - uses: actions/checkout@v4 15 | with: 16 | fetch-depth: 0 # All history + tags 17 | - name: Run action 18 | uses: ./test/test_on_self/ 19 | with: 20 | src: . 21 | dst: ./result 22 | language: en 23 | primary-color: black 24 | secondary-color: red 25 | hide-repository: ${{ matrix.hide-repository }} 26 | title: ${{ matrix.title }} 27 | - name: Verify result 28 | run: | 29 | test ! -z "$(ls -A ./result)" 30 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | markdown-test/ 2 | result/ -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "workbench.colorCustomizations": { 3 | "statusBar.background": "#222222", 4 | "statusBar.foreground": "#e7e7e7", 5 | "statusBarItem.hoverBackground": "#3b3b3b", 6 | "statusBarItem.remoteBackground": "#222222", 7 | "statusBarItem.remoteForeground": "#e7e7e7" 8 | }, 9 | "peacock.color": "#222222" 10 | } -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.13.2-alpine 2 | 3 | # Download PlantUML + dependencies 4 | RUN mkdir -p /usr/share/man/man1 && apk add --no-cache openjdk8 graphviz && \ 5 | wget -q -O plantuml.jar https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar && \ 6 | mkdir -p /opt/plantuml && mv plantuml.jar /opt/plantuml/plantuml.jar 7 | ENV ALLOW_PLANTUML_INCLUDE=true 8 | 9 | # Download Python Markdown + dependencies 10 | COPY config/requirements.txt /usr/local/src/requirements.txt 11 | RUN apk add --no-cache gcc git musl-dev libffi-dev && \ 12 | pip install --no-cache-dir -r /usr/local/src/requirements.txt && \ 13 | apk del gcc musl-dev libffi-dev 14 | 15 | # Configuration 16 | COPY config/mkdocs.yml /usr/local/src/mkdocs.yml 17 | COPY config/arithmatex.config.js /usr/local/src/arithmatex.config.js 18 | COPY config/theme.main.html /usr/local/src/theme.main.html 19 | COPY config/theme.404.html /usr/local/src/theme.404.html 20 | 21 | # Entrypoint 22 | COPY script/makedocs.sh /usr/local/bin/makedocs 23 | RUN chmod +x /usr/local/bin/makedocs 24 | ENTRYPOINT [ "makedocs" ] 25 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Luca Deluigi 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Markdown Docs 2 | _The same readme, built with this: [here](https://ldeluigi.github.io/markdown-docs/)!_ 3 | 4 | [![CI/CD](https://github.com/ldeluigi/markdown-docs/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ldeluigi/markdown-docs/actions/workflows/ci.yml) 5 | [![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ldeluigi/markdown-docs?logo=github)](https://github.com/ldeluigi/markdown-docs) 6 | [![Docker Pulls](https://img.shields.io/docker/pulls/deloo/markdown-docs?logo=docker)](https://hub.docker.com/r/deloo/markdown-docs) 7 | [![GitHub marketplace](https://img.shields.io/badge/marketplace-markdown--docs-blue?logo=github)](https://github.com/marketplace/actions/markdown-docs) 8 | [![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/ldeluigi/markdown-docs?include_prereleases&logo=github)](https://github.com/ldeluigi/markdown-docs/releases) 9 | 10 | This repository contains the definition of a Docker image that can be used both as a **[builder](#as-docker-builder)** stage and as an **[action](#as-github-action)**. 11 | 12 | **markdown-docs** is implemented as a jam of stuff you don't even need to know about. Just assume that everything is supported until you find that it's not, then submit an issue to add support for even that thing. Only if you really need it. 13 | 14 | ## Supported Markdown extensions: 15 | - The default, standard, Markdown syntax, described at [this website](https://daringfireball.net/projects/markdown/syntax), with [these differences](https://python-markdown.github.io/#differences). 16 | - **markdown_include**: Command that embeds a markdown file into another. Headers will be shifted to subheaders relative to enclosing header. See the [readme](https://github.com/cmacmackin/markdown-include/). 17 | - **plantuml_markdown**: Don't you know [PlantUML](https://plantuml.com/) already? For usage explanation see the [readme](https://github.com/mikitex70/plantuml-markdown#readme). Supports non-UML tags like `@startjson` or math equations too. 18 | - **arithmatex**: Provides mathematical style and fonts for expressions. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/). 19 | - **admonition** and **details**: Provides highlighted text cells for many purposes. See the [admonitions docs](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) and [details docs](https://facelessuser.github.io/pymdown-extensions/extensions/details/). Details are also called [collapsible blocks](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#collapsible-blocks). 20 | - **keys**: You can embed keyboard symbols in text. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/keys/). 21 | - **tabs**: Enables content tabs. See the [docs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/). 22 | - **tasklist**: Enables GitHub style tasks list. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/). 23 | - **abbreviations**: Enables explanations for abbrevations. See the [docs](https://python-markdown.github.io/extensions/abbreviations/). 24 | - **footnotes**: Enables footnotes. See the [docs](https://python-markdown.github.io/extensions/footnotes/). 25 | - **literate-nav**: Allows to customize navigation menus for each folder. The navigation menu must be specified inside a `SUMMARY.md` file. For more information see the [docs](https://oprypin.github.io/mkdocs-literate-nav/#usage). 26 | - **nl2br**: Enables newlines to be converted to `
` tags. See the [docs](https://python-markdown.github.io/extensions/nl2br/). 27 | - **callouts**: Enables Obsidian-styled callout blocks. For more information, see the [docs](https://github.com/sondregronas/mkdocs-callouts#usage). 28 | 29 | ## Supported plugins 30 | - **git-revision-date-localized**: Displays the last edit date of the page. The date appears automatically at the bottom if a git history is found. See the [docs](https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html) for more information. 31 | - **git-authors-plugin**: Displays git authors of the page. Authors appear automatically at the bottom if a git history is found. See the [docs](https://timvink.github.io/mkdocs-git-authors-plugin/index.html) for more information. 32 | - **notebooks**: `.ipynb` file rendering support. 33 | 34 | ## Usage 35 | You can use **markdown-docs** both as a [GitHub Acton](#as-github-action) or a [Docker builder stage](#as-docker-builder) inside your dockerfile. 36 | 37 | ### As GitHub Action 38 | To use **markdown-docs** as a GitHub Action, use the following syntax in your workflow: 39 | ```yaml 40 | - name: Generate HTML from Markdown 41 | uses: ldeluigi/markdown-docs@latest 42 | with: 43 | src: doc 44 | dst: generated 45 | ``` 46 | This means that every markdown file inside the `doc` folder in the current workspace will be converted and mapped to a corresponding HTML file inside the `generated` directory. You can pass `.` as src to search the entire repo for markdown files. `dst` folder will be emptied before generation. 47 | 48 | #### Additional information 49 | In order to make the "last edit date" plugin work you need to clone the full history of your documentation inside your CI. With GitHub actions this can be done using the option `fetch-depth: 0` with the `actions/checkout@v3` step. 50 | 51 | #### Complete usage example with all the parameters 52 | ```yaml 53 | - name: Generate HTML from Markdown 54 | uses: ldeluigi/markdown-docs@latest 55 | with: 56 | src: doc 57 | dst: generated 58 | title: Markdown Docs 59 | language: en 60 | icon: library 61 | primary-color: indigo 62 | secondary-color: indigo 63 | hide-repository: false 64 | ``` 65 | ##### Additional parameters info 66 | * `title` is an optional parameter (defaults to the name of the repository, such as `ldeluigi/markdown-docs` or `Documentation` if no repo is detected) that sets the title displayed at the top of the documentation website. 67 | * `language` is an optional paramater (defaults to `en`) that allows to change [language features](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) and [search features](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search). 68 | * `icon` is an optional parameter (defaults to `library`) that selects the main top-left icon of the documentation website. Can be one of the icons from [Material Design Icons](https://materialdesignicons.com). 69 | * `primary-color` is an optional parameter (defaults to `indigo`) that selects the main color of the documentation website. For more information, see the [docs](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#primary-color). 70 | * `secondary-color` is an optional parameter (defaults to `indigo`) that selects the accent color of the documentation website. For more information, see the [docs](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#accent-color). 71 | * `hide-repository` is an optional parameter (defaults to `false`) that, if set to `true`, will hide every reference to the source repo. Useful for private repos. 72 | 73 | ### As Docker builder 74 | To use **markdown-docs** as a Docker builder stage use the following syntax in your Dockerfile: 75 | ```dockerfile 76 | FROM deloo/markdown-docs AS builder 77 | 78 | COPY docs/ /home/src 79 | ENV WORKSPACE=/home 80 | RUN makedocs "src" "dst" 81 | 82 | FROM ... 83 | 84 | COPY --from=builder /home/dst /var/www/static/ 85 | ``` 86 | This means that first docker stage creates a container where it runs the makedocs script, then will copy the resulting, generated HTML files in the production image, specifically in `/var/www/static`. This can be useful for your static website hosting. See [the Wiki](https://github.com/ldeluigi/markdown-docs/wiki) for more examples. 87 | 88 | #### Environment variables 89 | There are some environment variables that control the behaviour of the builder. These are: 90 | ```dockerfile 91 | ENV WORKSPACE=/home 92 | # Optionals (with their default values) 93 | ENV TITLE=Markdown Docs 94 | ENV LANGUAGE=en 95 | ENV ICON=library 96 | ENV PRIMARY_COLOR=indigo 97 | ENV SECONDARY_COLOR=indigo 98 | ENV HIDE_REPOSITORY=false 99 | ``` 100 | * `WORKSPACE` selects the path in which the main script is run. This path should be the root of your working directory, inside which there are both the source folder and the destination folder. 101 | * `TITLE`, `LANGUAGE`, `ICON`, `PRIMARY_COLOR`, `SECONDARY_COLOR`, `HIDE_REPOSITORY` are all described in [this section](#additional-parameters-info). 102 | 103 | 104 | ## Notes about documenting your software 105 | The idea behind **markdown-docs** is that all the documentation that can be written in separate files from the code should be mantained like the code documentation, that is thinking about the content and not the appearence. In addition, some of the most important tools for documentation are UML diagrams. In particular, one of the most maintainable way to draw UMLs is [PlantUML](https://plantuml.com/), which can generate UML diagrams for a text specification. 106 | One of the most important features of **markdown-docs** is the support of PlantUML syntax embedded inside documentation sources, in Markdown. 107 | 108 | 109 | ## Contributing 110 | Fork this project and make PRs, if you can't you can create an issue. 111 | 112 | ### Local tests 113 | With **Docker** *(suggested)*: 114 | ```bash 115 | docker build -t markdown-docs . --no-cache 116 | docker run -e WORKSPACE=/github/workspace -v :/github/workspace markdown-docs . result/ 117 | ``` 118 | -------------------------------------------------------------------------------- /action.yml: -------------------------------------------------------------------------------- 1 | name: 'Markdown Docs' 2 | author: ldeluigi 3 | description: 'Generates a documentation website from Markdown files with many extensions: https://github.com/ldeluigi/markdown-docs#readme' 4 | branding: 5 | icon: 'file-text' 6 | color: 'gray-dark' 7 | inputs: 8 | src: 9 | description: > 10 | Source path. 11 | Default: . 12 | required: true 13 | default: '.' 14 | dst: 15 | description: > 16 | Output path. 17 | Default: docs 18 | required: true 19 | default: 'docs' 20 | language: 21 | description: > 22 | Language selector for mkdocs search feature and more. 23 | Default: en 24 | required: false 25 | default: 'en' 26 | icon: 27 | description: > 28 | One of https://materialdesignicons.com icons. 29 | Displayed at the top left, links to the home. 30 | Default: library 31 | required: false 32 | default: 'library' 33 | primary-color: 34 | description: > 35 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, 36 | light green, lime, yellow, amber, orange, deep orange. 37 | Default: indigo 38 | required: false 39 | default: indigo 40 | secondary-color: 41 | description: > 42 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, 43 | lime, yellow, amber, orange, deep orange. 44 | Default: indigo 45 | required: false 46 | default: indigo 47 | hide-repository: 48 | description: > 49 | If set to true, will generate a website that doesn't link back to the repository on GitHub. Defaults to false. 50 | required: false 51 | default: 'false' 52 | title: 53 | description: > 54 | The title for the documentation website. Defaults to the name of the repository. 55 | required: false 56 | default: ${{ github.repository }} 57 | runs: 58 | using: 'docker' 59 | image: 'docker://deloo/markdown-docs:0.8.2' 60 | env: 61 | TITLE: ${{ inputs.title }} 62 | LANGUAGE: ${{ inputs.language }} 63 | ICON: ${{ inputs.icon }} 64 | PRIMARY_COLOR: ${{ inputs.primary-color }} 65 | SECONDARY_COLOR: ${{ inputs.secondary-color }} 66 | HIDE_REPOSITORY: ${{ inputs.hide-repository }} 67 | args: 68 | - ${{ inputs.src }} 69 | - ${{ inputs.dst }} 70 | -------------------------------------------------------------------------------- /config/arithmatex.config.js: -------------------------------------------------------------------------------- 1 | window.MathJax = { 2 | tex: { 3 | inlineMath: [["\\(", "\\)"]], 4 | displayMath: [["\\[", "\\]"]], 5 | processEscapes: true, 6 | processEnvironments: true 7 | }, 8 | options: { 9 | ignoreHtmlClass: ".*|", 10 | processHtmlClass: "arithmatex" 11 | } 12 | }; 13 | 14 | document.addEventListener("DOMContentLoaded", function() { 15 | MathJax.typesetPromise() 16 | }); -------------------------------------------------------------------------------- /config/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: !ENV TITLE 2 | site_url: "" 3 | use_directory_urls: false 4 | docs_dir: !ENV SRC 5 | repo_url: !ENV [REPO_URL, null] 6 | edit_uri: !ENV [EDIT_URI, ""] 7 | theme: 8 | name: material 9 | custom_dir: !ENV SRC_THEME 10 | language: !ENV [LANGUAGE, "en"] 11 | icon: 12 | logo: !ENV [ICON, "material/library"] 13 | palette: 14 | - media: "(prefers-color-scheme: light)" 15 | scheme: default 16 | primary: !ENV [PRIMARY_COLOR, "indigo"] 17 | accent: !ENV [SECONDARY_COLOR, "indigo"] 18 | toggle: 19 | icon: material/toggle-switch-off-outline 20 | name: Switch to dark mode 21 | - media: "(prefers-color-scheme: dark)" 22 | scheme: slate 23 | primary: !ENV [PRIMARY_COLOR, "indigo"] 24 | accent: !ENV [SECONDARY_COLOR, "indigo"] 25 | toggle: 26 | icon: material/toggle-switch 27 | name: Switch to light mode 28 | 29 | plugins: 30 | - exclude: 31 | glob: 32 | - .git/* 33 | - search: 34 | lang: !ENV [LANGUAGE, "en"] 35 | - offline 36 | # - drawio-exporter: # Allows embeddding .drawio files 37 | # drawio_executable: /drawio.AppImage 38 | # # Diagrams are cached to speed up site generation. The default path is 39 | # # drawio-exporter, relative to the documentation directory. 40 | # cache_dir: /tmp/drawio-exporter 41 | # format: svg 42 | # embed_format: '{img_open}{img_src}{img_close}' 43 | # sources: '*.drawio' 44 | - callouts 45 | - mkdocs-jupyter: 46 | include: ["*.ipynb"] 47 | execute: false 48 | ignore_h1_titles: true 49 | include_source: true 50 | - literate-nav: 51 | nav_file: SUMMARY.md 52 | implicit_index: true 53 | - git-revision-date-localized: 54 | type: datetime 55 | timezone: UTC 56 | locale: en 57 | fallback_to_build_date: true 58 | enable_creation_date: true 59 | - git-authors: 60 | show_contribution: true 61 | show_line_count: true 62 | count_empty_lines: false 63 | fallback_to_empty: true 64 | - print-site: # Must be the last one 65 | add_to_navigation: true 66 | print_page_title: 'Print as PDF' 67 | # Table of contents 68 | add_table_of_contents: true 69 | toc_title: 'Index' 70 | toc_depth: 3 71 | # Content-related 72 | add_full_urls: false 73 | enumerate_headings: true 74 | enumerate_headings_depth: 3 75 | enumerate_figures: true 76 | path_to_pdf: "" 77 | add_print_site_banner: true 78 | 79 | markdown_extensions: 80 | - markdown_include.include: 81 | base_path: !ENV SRC 82 | inheritHeadingDepth: true 83 | throwException: false 84 | - plantuml_markdown: 85 | cachedir: /tmp # set a non-empty value to enable caching 86 | format: svg # default diagram image format 87 | classes: uml # default diagram classes 88 | title: UML diagram # default title (tooltip) for diagram images 89 | alt: UML diagram image # default `alt` attribute for diagram images 90 | priority: 100 # plugin priority; the higher, the sooner will be applied (default 23) 91 | theme: plain # default PlantUML theme 92 | plantuml_cmd: !ENV PLANTUML_CMD # path to the PlantUML jar file 93 | - pymdownx.arithmatex: 94 | generic: true 95 | - nl2br 96 | - admonition 97 | - sane_lists 98 | - pymdownx.details 99 | - pymdownx.superfences: 100 | custom_fences: 101 | - name: mermaid 102 | class: mermaid 103 | format: !!python/name:pymdownx.superfences.fence_code_format 104 | - pymdownx.highlight 105 | - pymdownx.inlinehilite 106 | - pymdownx.keys 107 | - pymdownx.tabbed 108 | - pymdownx.tasklist: 109 | custom_checkbox: true 110 | clickable_checkbox: false 111 | - abbr 112 | - footnotes 113 | 114 | 115 | extra_javascript: 116 | - js/arithmatex.config.js 117 | - https://polyfill.io/v3/polyfill.min.js?features=es6 118 | - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js -------------------------------------------------------------------------------- /config/requirements.txt: -------------------------------------------------------------------------------- 1 | mkdocs==1.6.1 2 | mkdocs-exclude==1.0.2 3 | mkdocs-material==9.6.14 4 | #mkdocs-drawio-exporter 5 | mkdocs-git-revision-date-localized-plugin==1.4.5 6 | mkdocs-git-authors-plugin==0.9.5 7 | mkdocs-print-site-plugin==2.7.2 8 | mkdocs-literate-nav==0.6.2 9 | mkdocs-jupyter==0.25.1 10 | mkdocs-callouts==1.16.0 11 | plantuml-markdown==3.11.1 12 | markdown-include==0.8.1 13 | -------------------------------------------------------------------------------- /config/theme.404.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 12 | Page Redirection 13 | 14 | 15 | If you are not redirected automatically, follow this link. 16 | 17 | -------------------------------------------------------------------------------- /config/theme.main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | {% block content %} 3 | {{ super() }} 4 | 5 | {% if git_page_authors %} 6 |
7 | 8 | Authors: {{ git_page_authors | default('enable mkdocs-git-authors-plugin') }} 9 | 10 |
11 | {% endif %} 12 | {% endblock %} 13 | {% block config %} 14 | {{ super() }} 15 | {% if "localsearch" in config["plugins"] %} 16 | 17 | {% endif %} 18 | {% endblock %} -------------------------------------------------------------------------------- /local.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -e 4 | export MSYS_NO_PATHCONV=1 5 | 6 | if [ -z "$1" -o -z "$2" ]; then 7 | echo "Usage: $0 " 8 | exit 1 9 | fi 10 | 11 | docker build -t mdocs-local . 12 | docker run --rm -e 'WORKSPACE=/github/workspace' -v "$(pwd):/github/workspace" mdocs-local "${1%/}" "${2%/}" 13 | -------------------------------------------------------------------------------- /script/makedocs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # Fail script if a command fails 3 | set -e 4 | # Ignore safe directory errors 5 | git config --global --add safe.directory '*' 6 | # Setup 7 | WORKSPACE="${WORKSPACE:-${GITHUB_WORKSPACE:-/}}" 8 | if [ "${HIDE_REPOSITORY}" = "true" ]; then 9 | echo "Hiding repository location from documentation." 10 | unset GITHUB_REPOSITORY 11 | fi 12 | export TITLE="${TITLE:-${GITHUB_REPOSITORY:-Documentation}}" 13 | # Source folder 14 | SRC=${1#.} 15 | # Check if documentation is from GitHub 16 | if [ ! -z "${GITHUB_SERVER_URL}" -a ! -z "${GITHUB_REPOSITORY}" ] ; then 17 | export GIT=1 18 | export REPO_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" 19 | EDIT_URI="${SRC#/}" 20 | case "${GITHUB_REF}" in 21 | refs/heads/* ) 22 | BRANCH_NAME=${GITHUB_REF#refs/heads/} 23 | esac 24 | if [ ! -z "${BRANCH_NAME}" ] ; then 25 | export EDIT_URI="edit/${BRANCH_NAME}/${EDIT_URI}" 26 | fi 27 | fi 28 | export SRC=${WORKSPACE%/}/${SRC#/} 29 | # PlantUML !include root folder 30 | export PLANTUML_CMD="java -Dplantuml.include.path=${SRC} -jar /opt/plantuml/plantuml.jar" 31 | # Destination folder 32 | RELATIVE_DST=${2#.} 33 | RELATIVE_DST=${RELATIVE_DST#/} 34 | RELATIVE_DST=${RELATIVE_DST%/} 35 | DST=${WORKSPACE%/}/${RELATIVE_DST} 36 | # Temp files 37 | TMP_DST=/tmp/makedocs 38 | echo "Source: ${SRC}; Destination: ${DST};" 39 | # MkDocs default config 40 | if [ ! -z "${ICON}" ] ; then 41 | export ICON=material/${ICON##*/} 42 | fi 43 | # Generate index if absent 44 | if [ ! -f "${SRC}/index.md" -a ! -f "${SRC}/README.md" ] ; then 45 | echo "Index file (index.md) not found. It will be created using a script..." 46 | echo "# ${TITLE}" > "${SRC}/index.md" 47 | CLEAN_INDEX=true 48 | fi 49 | # Copy static template files 50 | export SRC_THEME="${SRC}/theme" 51 | mkdir -p "${SRC_THEME}" && cp -f /usr/local/src/theme.main.html "${SRC_THEME}/main.html" && cp -f /usr/local/src/theme.404.html "${SRC_THEME}/404.html" 52 | CLEAN_THEME=true 53 | # Convert docs to temp folder 54 | ( cd "${SRC}" ; mkdocs build -c -f /usr/local/src/mkdocs.yml -d "${TMP_DST}" ) 55 | # Start cleanup phase 56 | echo "Cleanup..." 57 | # Copy static assets to be added 58 | mkdir -p "${TMP_DST}/js" && cp -f /usr/local/src/arithmatex.config.js "${TMP_DST}/js/arithmatex.config.js" 59 | # Prepare destination 60 | rm -rf "${DST}" 61 | # Move results to destination 62 | mv -f "${TMP_DST}" "${DST}" 63 | # Cleanup 64 | if [ "${CLEAN_INDEX}" = true ] ; then 65 | rm "${SRC}/index.md" 66 | fi 67 | if [ "${CLEAN_THEME}" = true ] ; then 68 | rm -rf "${SRC_THEME}" 69 | fi 70 | # End task 71 | echo "Done" 72 | -------------------------------------------------------------------------------- /test/test_on_ghcr/action.yml: -------------------------------------------------------------------------------- 1 | name: 'Test on GitHub Container Registry' 2 | author: ldeluigi 3 | description: 'Generates a documentation website from Markdown files with many extensions: https://github.com/ldeluigi/markdown-docs#readme' 4 | branding: 5 | icon: 'file-text' 6 | color: 'gray-dark' 7 | inputs: 8 | src: 9 | description: > 10 | Source path. 11 | Default: . 12 | required: true 13 | default: '.' 14 | dst: 15 | description: > 16 | Output path. 17 | Default: docs 18 | required: true 19 | default: 'docs' 20 | language: 21 | description: > 22 | Language selector for mkdocs search feature and more. 23 | Default: en 24 | required: false 25 | default: 'en' 26 | icon: 27 | description: > 28 | One of https://materialdesignicons.com icons. 29 | Displayed at the top left, links to the home. 30 | Default: library 31 | required: false 32 | default: 'library' 33 | primary-color: 34 | description: > 35 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, 36 | light green, lime, yellow, amber, orange, deep orange. 37 | Default: indigo 38 | required: false 39 | default: indigo 40 | secondary-color: 41 | description: > 42 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, 43 | lime, yellow, amber, orange, deep orange. 44 | Default: indigo 45 | required: false 46 | default: indigo 47 | hide-repository: 48 | description: > 49 | If set to true, will generate a website that doesn't link back to the repository on GitHub. Defaults to false. 50 | required: false 51 | default: 'false' 52 | title: 53 | description: > 54 | The title for the documentation website. Defaults to the name of the repository. 55 | required: false 56 | default: ${{ github.repository }} 57 | runs: 58 | using: 'docker' 59 | image: 'docker://ghcr.io/ldeluigi/markdown-docs' 60 | env: 61 | TITLE: ${{ inputs.title }} 62 | LANGUAGE: ${{ inputs.language }} 63 | ICON: ${{ inputs.icon }} 64 | PRIMARY_COLOR: ${{ inputs.primary-color }} 65 | SECONDARY_COLOR: ${{ inputs.secondary-color }} 66 | HIDE_REPOSITORY: ${{ inputs.hide-repository }} 67 | args: 68 | - ${{ inputs.src }} 69 | - ${{ inputs.dst }} 70 | -------------------------------------------------------------------------------- /test/test_on_hub/action.yml: -------------------------------------------------------------------------------- 1 | name: 'Docker Hub test' 2 | author: ldeluigi 3 | description: 'Generates a documentation website from Markdown files with many extensions: https://github.com/ldeluigi/markdown-docs#readme' 4 | branding: 5 | icon: 'file-text' 6 | color: 'gray-dark' 7 | inputs: 8 | src: 9 | description: > 10 | Source path. 11 | Default: . 12 | required: true 13 | default: '.' 14 | dst: 15 | description: > 16 | Output path. 17 | Default: docs 18 | required: true 19 | default: 'docs' 20 | language: 21 | description: > 22 | Language selector for mkdocs search feature and more. 23 | Default: en 24 | required: false 25 | default: 'en' 26 | icon: 27 | description: > 28 | One of https://materialdesignicons.com icons. 29 | Displayed at the top left, links to the home. 30 | Default: library 31 | required: false 32 | default: 'library' 33 | primary-color: 34 | description: > 35 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, 36 | light green, lime, yellow, amber, orange, deep orange. 37 | Default: indigo 38 | required: false 39 | default: indigo 40 | secondary-color: 41 | description: > 42 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, 43 | lime, yellow, amber, orange, deep orange. 44 | Default: indigo 45 | required: false 46 | default: indigo 47 | hide-repository: 48 | description: > 49 | If set to true, will generate a website that doesn't link back to the repository on GitHub. Defaults to false. 50 | required: false 51 | default: 'false' 52 | title: 53 | description: > 54 | The title for the documentation website. Defaults to the name of the repository. 55 | required: false 56 | default: ${{ github.repository }} 57 | runs: 58 | using: 'docker' 59 | image: 'docker://deloo/markdown-docs' 60 | env: 61 | TITLE: ${{ inputs.title }} 62 | LANGUAGE: ${{ inputs.language }} 63 | ICON: ${{ inputs.icon }} 64 | PRIMARY_COLOR: ${{ inputs.primary-color }} 65 | SECONDARY_COLOR: ${{ inputs.secondary-color }} 66 | HIDE_REPOSITORY: ${{ inputs.hide-repository }} 67 | args: 68 | - ${{ inputs.src }} 69 | - ${{ inputs.dst }} 70 | -------------------------------------------------------------------------------- /test/test_on_self/action.yml: -------------------------------------------------------------------------------- 1 | name: 'Markdown Docs' 2 | author: ldeluigi 3 | description: 'Generates file based on documentation written in Markdown (with many extensions, see https://github.com/ldeluigi/markdown-docs#readme) based on MkDocs and Python Markdown' 4 | branding: 5 | icon: 'file-text' 6 | color: 'gray-dark' 7 | inputs: 8 | src: 9 | description: 'Source path' 10 | required: true 11 | default: '.' 12 | dst: 13 | description: 'Output path' 14 | required: true 15 | default: 'docs' 16 | language: 17 | description: > 18 | Language selector for mkdocs search feature and more. 19 | Default: en 20 | required: false 21 | default: 'en' 22 | icon: 23 | description: > 24 | One of https://materialdesignicons.com icons. 25 | Displayed at the top left, links to the home. 26 | Default: library 27 | required: false 28 | default: 'library' 29 | primary-color: 30 | description: > 31 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, 32 | light green, lime, yellow, amber, orange, deep orange. 33 | Default: indigo 34 | required: false 35 | default: indigo 36 | secondary-color: 37 | description: > 38 | One of red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, 39 | lime, yellow, amber, orange, deep orange. 40 | Default: indigo 41 | required: false 42 | default: indigo 43 | hide-repository: 44 | description: > 45 | If set to true, will generate a website that doesn't link back to the repository on GitHub. Defaults to false. 46 | required: false 47 | default: 'false' 48 | title: 49 | description: > 50 | The title for the documentation website. Defaults to the name of the repository. 51 | required: false 52 | default: ${{ github.repository }} 53 | runs: 54 | using: 'docker' 55 | image: ../../Dockerfile 56 | env: 57 | TITLE: ${{ inputs.title }} 58 | LANGUAGE: ${{ inputs.language }} 59 | ICON: ${{ inputs.icon }} 60 | PRIMARY_COLOR: ${{ inputs.primary-color }} 61 | SECONDARY_COLOR: ${{ inputs.secondary-color }} 62 | HIDE_REPOSITORY: ${{ inputs.hide-repository }} 63 | args: 64 | - ${{ inputs.src }} 65 | - ${{ inputs.dst }} 66 | --------------------------------------------------------------------------------