The fastest way to learn Markdown is to go to CommonMark website and go through a 60 second cheatsheet or 10 minute tutorial

Znai is available as Command Line Maven Plugin Both command line and maven plugin lets you to build documentation website and also run preview server during documentation writing process

CLI download Download and unzip znai Add it to your PATH Brew brew install testingisdocumenting brew znai

Note consider adding a separate module for documentation in the multi module maven project <plugin> <groupId>org testingisdocumenting znai< groupId> <artifactId>znai maven plugin< artifactId> <version>1 73< version> < plugin>

To create a minimum set of files for your documentation execute CLI znai new Maven mvn znai new Listed above directories and files will be generated in the current directory znai | chapter one | page one md | page two md | chapter two | page three md | page four md | toc | lookup paths | meta json

Znai comes with mode In mode znai monitors changes you apply to the documentation files and notifies browser to navigates to the right page and highlights the changes To start preview mode navigate to the documentation directory if you used scaffold and run CLI znai preview port port number Maven mvn znai preview <plugin> <groupId>org testingisdocumenting znai< groupId> <artifactId>znai maven plugin< artifactId> <version>1 73< version> <configuration> <port>3334< port> < optional override of default value 3333 > < configuration> < plugin> Open URL output by the command and open in a browser Blue eye icon in the top right corner indicates that preview is on Open any text editor modify and save a markdown file Changes will be reflected in the browser preview preview znai

To build static documentation site you need to provide Documentation id becomes part of your url and is also used inside generated HTMLs to reference static resources using absolute path For example znai original documentation is hosted on https testingisdocumenting org znai and documentation id is This original page is hosted on https testingisdocumenting org znai introduction getting started znai generates each page as index html and puts inside directories to make it possible to have an extension less urls To make it easier to handle static resources loading Znai builds all the urls inside HTML pages using absolute locations and that s why it is required to provide during the site generation To generate static site use CLI znai doc id my docs deploy path to static content Maven <plugin> <groupId>org testingisdocumenting znai< groupId> <artifactId>znai maven plugin< artifactId> <version>1 73< version> <configuration> <docId>project name< docId> <deployRoot> path to static content< deployRoot> < default is $ project build directory > < configuration> < plugin> documentation id znai documentation id

To deploy to GitHub Pages use GitHub Pages Action Here is an example of znai publishing its documentation to github pages name deploy documentation uses peaceiris actions gh pages@v3 with github_token $ secrets GITHUB_TOKEN publish_dir znai docs target znai

Znai has enterprise mode that lets you run Documentation hub inside your organization It is completely free and open sourced Please create a GitHub Issue if you want to try it out I don t document it yet as I only have a couple of scenarios I tried it on and I need more input