Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ldeluigi/markdown-docs
Action/docker image that transforms your markdown into a static website. No need for particular configuration: it just works.
https://github.com/ldeluigi/markdown-docs
docker-image docs documentation markdown mkdocs mkdocs-docker mkdocs-site plantuml wiki
Last synced: 2 months ago
JSON representation
Action/docker image that transforms your markdown into a static website. No need for particular configuration: it just works.
- Host: GitHub
- URL: https://github.com/ldeluigi/markdown-docs
- Owner: ldeluigi
- License: mit
- Created: 2021-05-14T18:59:14.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-09-30T08:27:08.000Z (2 months ago)
- Last Synced: 2024-09-30T22:14:29.819Z (2 months ago)
- Topics: docker-image, docs, documentation, markdown, mkdocs, mkdocs-docker, mkdocs-site, plantuml, wiki
- Language: Shell
- Homepage: https://ldeluigi.github.io/markdown-docs
- Size: 1.75 MB
- Stars: 21
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- project-awesome - ldeluigi/markdown-docs - Action/docker image that transforms your markdown into a static website. No need for particular configuration: it just works. (Shell)
README
# Markdown Docs
_The same readme, built with this: [here](https://ldeluigi.github.io/markdown-docs/)!_
[](https://github.com/ldeluigi/markdown-docs/actions/workflows/ci.yml)
[](https://github.com/ldeluigi/markdown-docs)
[](https://hub.docker.com/r/deloo/markdown-docs)
[](https://github.com/marketplace/actions/markdown-docs)
[](https://github.com/ldeluigi/markdown-docs/releases)
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)**.
**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.
## Supported Markdown extensions:
- The default, standard, Markdown syntax, described at [this website](https://daringfireball.net/projects/markdown/syntax), with [these differences](https://python-markdown.github.io/#differences).
- **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/).
- **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.
- **arithmatex**: Provides mathematical style and fonts for expressions. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/).
- **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).
- **keys**: You can embed keyboard symbols in text. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/keys/).
- **tabs**: Enables content tabs. See the [docs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/).
- **tasklist**: Enables GitHub style tasks list. See the [docs](https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/).
- **abbreviations**: Enables explanations for abbrevations. See the [docs](https://python-markdown.github.io/extensions/abbreviations/).
- **footnotes**: Enables footnotes. See the [docs](https://python-markdown.github.io/extensions/footnotes/).
- **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).
- **nl2br**: Enables newlines to be converted to `
` tags. See the [docs](https://python-markdown.github.io/extensions/nl2br/).
- **callouts**: Enables Obsidian-styled callout blocks. For more information, see the [docs](https://github.com/sondregronas/mkdocs-callouts#usage).
## Supported plugins
- **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.
- **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.
- **notebooks**: `.ipynb` file rendering support.
## Usage
You can use **markdown-docs** both as a [GitHub Acton](#as-github-action) or a [Docker builder stage](#as-docker-builder) inside your dockerfile.
### As GitHub Action
To use **markdown-docs** as a GitHub Action, use the following syntax in your workflow:
```yaml
- name: Generate HTML from Markdown
uses: ldeluigi/markdown-docs@latest
with:
src: doc
dst: generated
```
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.
#### Additional information
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.
#### Complete usage example with all the parameters
```yaml
- name: Generate HTML from Markdown
uses: ldeluigi/markdown-docs@latest
with:
src: doc
dst: generated
title: Markdown Docs
language: en
icon: library
primary-color: indigo
secondary-color: indigo
hide-repository: false
```
##### Additional parameters info
* `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.
* `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).
* `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).
* `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).
* `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).
* `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.
### As Docker builder
To use **markdown-docs** as a Docker builder stage use the following syntax in your Dockerfile:
```dockerfile
FROM deloo/markdown-docs AS builder
COPY docs/ /home/src
ENV WORKSPACE=/home
RUN makedocs "src" "dst"
FROM ...
COPY --from=builder /home/dst /var/www/static/
```
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.
#### Environment variables
There are some environment variables that control the behaviour of the builder. These are:
```dockerfile
ENV WORKSPACE=/home
# Optionals (with their default values)
ENV TITLE=Markdown Docs
ENV LANGUAGE=en
ENV ICON=library
ENV PRIMARY_COLOR=indigo
ENV SECONDARY_COLOR=indigo
ENV HIDE_REPOSITORY=false
```
* `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.
* `TITLE`, `LANGUAGE`, `ICON`, `PRIMARY_COLOR`, `SECONDARY_COLOR`, `HIDE_REPOSITORY` are all described in [this section](#additional-parameters-info).
## Notes about documenting your software
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.
One of the most important features of **markdown-docs** is the support of PlantUML syntax embedded inside documentation sources, in Markdown.
## Contributing
Fork this project and make PRs, if you can't you can create an issue.
### Local tests
With **Docker** *(suggested)*:
```bash
docker build -t markdown-docs . --no-cache
docker run -e WORKSPACE=/github/workspace -v :/github/workspace markdown-docs . result/
```