{"id":13910990,"url":"https://github.com/ldeluigi/markdown-docs","last_synced_at":"2025-07-17T14:33:54.327Z","repository":{"id":36960139,"uuid":"367455309","full_name":"ldeluigi/markdown-docs","owner":"ldeluigi","description":"Action/docker image that transforms your markdown into a static website. No need for particular configuration: it just works.","archived":false,"fork":false,"pushed_at":"2025-07-07T09:46:56.000Z","size":2060,"stargazers_count":24,"open_issues_count":1,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-07T10:55:28.442Z","etag":null,"topics":["docker-image","docs","documentation","markdown","mkdocs","mkdocs-docker","mkdocs-site","plantuml","wiki"],"latest_commit_sha":null,"homepage":"https://ldeluigi.github.io/markdown-docs/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ldeluigi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2021-05-14T18:59:14.000Z","updated_at":"2025-07-07T09:45:52.000Z","dependencies_parsed_at":"2024-02-12T22:38:49.034Z","dependency_job_id":"7f589b20-996c-457b-892e-cad127f2760a","html_url":"https://github.com/ldeluigi/markdown-docs","commit_stats":{"total_commits":414,"total_committers":5,"mean_commits":82.8,"dds":0.5507246376811594,"last_synced_commit":"75b76780b1894a8a296a286620ee3b413f7bb0c2"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/ldeluigi/markdown-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldeluigi%2Fmarkdown-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldeluigi%2Fmarkdown-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldeluigi%2Fmarkdown-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldeluigi%2Fmarkdown-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ldeluigi","download_url":"https://codeload.github.com/ldeluigi/markdown-docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldeluigi%2Fmarkdown-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265617036,"owners_count":23798953,"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":["docker-image","docs","documentation","markdown","mkdocs","mkdocs-docker","mkdocs-site","plantuml","wiki"],"created_at":"2024-08-07T00:01:53.403Z","updated_at":"2025-07-17T14:33:54.296Z","avatar_url":"https://github.com/ldeluigi.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Markdown Docs\n_The same readme, built with this: [here](https://ldeluigi.github.io/markdown-docs/)!_  \n\n[![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)\n[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ldeluigi/markdown-docs?logo=github)](https://github.com/ldeluigi/markdown-docs)\n[![Docker Pulls](https://img.shields.io/docker/pulls/deloo/markdown-docs?logo=docker)](https://hub.docker.com/r/deloo/markdown-docs)\n[![GitHub marketplace](https://img.shields.io/badge/marketplace-markdown--docs-blue?logo=github)](https://github.com/marketplace/actions/markdown-docs)\n[![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/ldeluigi/markdown-docs?include_prereleases\u0026logo=github)](https://github.com/ldeluigi/markdown-docs/releases)\n\nThis 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)**.\n\n**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.\n\n## Supported Markdown extensions:\n- The default, standard, Markdown syntax, described at [this website](https://daringfireball.net/projects/markdown/syntax), with [these differences](https://python-markdown.github.io/#differences).\n- **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/).\n- **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.\n- **arithmatex**: Provides mathematical style and fonts for expressions. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/).\n- **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).\n- **keys**: You can embed keyboard symbols in text. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/keys/).\n- **tabs**: Enables content tabs. See the [docs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/).\n- **tasklist**: Enables GitHub style tasks list. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/).\n- **abbreviations**: Enables explanations for abbrevations. See the [docs](https://python-markdown.github.io/extensions/abbreviations/).\n- **footnotes**: Enables footnotes. See the [docs](https://python-markdown.github.io/extensions/footnotes/).\n- **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).\n- **nl2br**: Enables newlines to be converted to `\u003cbr\u003e` tags. See the [docs](https://python-markdown.github.io/extensions/nl2br/).\n- **callouts**: Enables Obsidian-styled callout blocks. For more information, see the [docs](https://github.com/sondregronas/mkdocs-callouts#usage).\n\n## Supported plugins\n- **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.\n- **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.\n- **notebooks**: `.ipynb` file rendering support.\n\n## Usage\nYou can use **markdown-docs** both as a [GitHub Acton](#as-github-action) or a [Docker builder stage](#as-docker-builder) inside your dockerfile.\n\n### As GitHub Action\nTo use **markdown-docs** as a GitHub Action, use the following syntax in your workflow:\n```yaml\n      - name: Generate HTML from Markdown\n        uses: ldeluigi/markdown-docs@latest\n        with:\n          src: doc\n          dst: generated\n```\nThis 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.\n\n#### Additional information\nIn 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.\n\n#### Complete usage example with all the parameters\n```yaml\n      - name: Generate HTML from Markdown\n        uses: ldeluigi/markdown-docs@latest\n        with:\n          src: doc\n          dst: generated\n          title: Markdown Docs\n          language: en\n          icon: library\n          primary-color: indigo\n          secondary-color: indigo\n          hide-repository: false\n```\n##### Additional parameters info\n* `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.\n* `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).\n* `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).\n* `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).\n* `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).\n* `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.\n\n### As Docker builder\nTo use **markdown-docs** as a Docker builder stage use the following syntax in your Dockerfile:  \n```dockerfile\nFROM deloo/markdown-docs AS builder\n\nCOPY docs/ /home/src\nENV WORKSPACE=/home\nRUN makedocs \"src\" \"dst\"\n\nFROM ...\n\nCOPY --from=builder /home/dst /var/www/static/\n```\nThis 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.\n\n#### Environment variables\nThere are some environment variables that control the behaviour of the builder. These are:\n```dockerfile\nENV WORKSPACE=/home\n# Optionals (with their default values)\nENV TITLE=Markdown Docs\nENV LANGUAGE=en\nENV ICON=library\nENV PRIMARY_COLOR=indigo\nENV SECONDARY_COLOR=indigo\nENV HIDE_REPOSITORY=false\n```\n* `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.\n* `TITLE`, `LANGUAGE`, `ICON`, `PRIMARY_COLOR`, `SECONDARY_COLOR`, `HIDE_REPOSITORY` are all described in [this section](#additional-parameters-info).\n\n\n## Notes about documenting your software\nThe 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.  \nOne of the most important features of **markdown-docs** is the support of PlantUML syntax embedded inside documentation sources, in Markdown.\n\n\n## Contributing\nFork this project and make PRs, if you can't you can create an issue.\n\n### Local tests\nWith **Docker** *(suggested)*:\n```bash\ndocker build -t markdown-docs . --no-cache\ndocker run -e WORKSPACE=/github/workspace -v \u003cYOUR-CURRENT-WORKING-DIRECTORY\u003e:/github/workspace markdown-docs . result/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fldeluigi%2Fmarkdown-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fldeluigi%2Fmarkdown-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fldeluigi%2Fmarkdown-docs/lists"}