Action/docker image that transforms your markdown into a static website. No need for particular configuration: it just works.
MIT License
The same readme, built with this: here!
This repository contains the definition of a Docker image that can be used both as a builder stage and as an 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.
@startjson
or math equations too.SUMMARY.md
file. For more information see the docs.<br>
tags. See the docs..ipynb
file rendering support.You can use markdown-docs both as a GitHub Acton or a Docker builder stage inside your dockerfile.
To use markdown-docs as a GitHub Action, use the following syntax in your workflow:
- 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.
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.
- 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
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 and search features.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.primary-color
is an optional parameter (defaults to indigo
) that selects the main color of the documentation website. For more information, see the docs.secondary-color
is an optional parameter (defaults to indigo
) that selects the accent color of the documentation website. For more information, see the docs.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.To use markdown-docs as a Docker builder stage use the following syntax in your 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 for more examples.
There are some environment variables that control the behaviour of the builder. These are:
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.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, 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.
Fork this project and make PRs, if you can't you can create an issue.
With Docker (suggested):
docker build -t markdown-docs . --no-cache
docker run -e WORKSPACE=/github/workspace -v <YOUR-CURRENT-WORKING-DIRECTORY>:/github/workspace markdown-docs . result/