Reading Time: 3 minutes
Writing documentation from a user perspective has always been a challenging job for Developers.Markdowns allows the developers to write docs using an easy-to-read, easy-to-write plain text format.
But the challenge does not end here, providing users with offline documentation in book like format is also becoming essential and popular. Also a large number of organisations contributing to open source do not want to spend extra resources in creating separate documentation for gitHub and website etc.
In this blog I am going to discuss simple ways in which your markdown files can be used to cater to your website and other documentation needs.
Let us discuss how we can utilise our markdowns to design documentation for website. There are several maven plugins, we will be talking about two of these namely:
1. Maven Doxia
2. Markdown-page-generator Plugin
Maven Doxia
Going by the apache definition ‘Doxia is a content generation framework which aims to provide its users with powerful techniques for generating static and dynamic content: Doxia can be used in web-based publishing context to generate static sites, in addition to being incorporated into dynamic content generation systems like blogs, wikis and content management systems.’
Discussing Doxia in great length would take several blogs itself, so let us just discuss the functionality of using Doxia to convert markdowns to html.
Step 1: Create a Maven Project
Step 2: Add the following plugin in the pom.xml
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.2</version>
<dependencies>
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-markdown</artifactId>
<version>1.3</version>
</dependency>
</dependencies>
<configuration>
<inputEncoding>UTF-8</inputEncoding>
<outputEncoding>UTF-8</outputEncoding>
</configuration>
</plugin>
</plugins>
</build>
Step 3: Add the markdowns in following structure
src/site/markdown
Step 4: mvn site command can be used to generate the html(s) from the markdowns
Markdown-page-generator Plugin
This Plugin creates static HTML pages with Maven and Markdown. Underlying it is a pegdown Markdown processor. The plugin is simple to use and integrate. It allows you to configure the input and output directories, which files to copy and which pegdown options are used. We can also include a custom header and footer and general title.
Adding headers and footers into generated html(s) allows us to customize and style the html(s).
The default configuration of input and output directories can be easily overridden:
inputDirectory : ${project.basedir}/src/main/resources/markdown/
outputDirectory : ${project.build.directory}/html/
Let us discuss the steps to convert markdowns to html using this:
Step 1:Create a Maven project
Step 2: Add the plugin to pom.xml
<build>
<plugins>
<plugin>
<groupId>com.ruleoftech</groupId>
<artifactId>markdown-page-generator-plugin</artifactId>
<version>0.10</version>
<executions>
<execution>
<phase>process-sources</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
This is a simple configuration to generate html(s).
Alternatively we can add custom header and footer
<plugin>
<groupId>com.ruleoftech</groupId>
<artifactId>markdown-page-generator-plugin</artifactId>
<version>0.10</version>
<executions>
<execution>
<phase>process-sources</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<headerHtmlFile>${project.basedir}/src/main/resources/markdown/html/header.html
<footerHtmlFile>${project.basedir}/src/main/resources/markdown/html/footer.html
<copyDirectories>css,js</copyDirectories>
</configuration>
</plugin>
Additional information regarding the input and output source can be added.
Step 3: run mvn install to generate the html.
Let us now discuss, how we can generate offline or book form documentation from these markdown files.
We can use Plugins like Doxia and Maven–pdf plugin to generate books from these markdown files.
Following below is a quick guide to generate pdf document from your markdowns.
Step 1: Create a Maven Project
Step 2: Add all markdown files in a folder
Step 3: Add the following plugin to your pom.xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pdf-plugin</artifactId>
<executions>
<execution>
<id>pdf</id>
<phase>site</phase>
<goals>
<goal>pdf</goal>
</goals>
<configuration>
<outputDirectory>${project.reporting.outputDirectory}</outputDirectory>
<includeReports>false</includeReports>
</configuration>
</execution>
</executions>
</plugin>
Step 4: Add a file called pdf.xml. This file acts like a book descriptor. It is optional. It acts like an indexer which can be used to sequence the content in the pdf-book. Absence of this file allows the entire folder of markdowns to be written into pdf-book in no particular order as specified in the site.xml.
Step 5: Command mvn pdf:pdf is used to generate the pdf.
Please note that by default, the PDF plugin generates a PDF document which aggregates all your site documents. If you wish to generate each site document individually, you need to add following parameter -Daggregate=false in the command line.
A sample of pdf.xml is given below :
<document outputName=”demo-pdf-plugin”>
<meta>
<title>PDF Plugin Demo</title>
<author>Knoldus</author>
</meta>
<toc name=”Table of Contents”>
<item name=”Introduction” ref=”index.md”/>
<item name=”Usage” ref=”usage.md”/>
<item name=”FAQ” ref=”faq.md”/>
</toc>
<cover>
<coverTitle>${project.name}</coverTitle>
<coverSubTitle>v. ${project.version}</coverSubTitle>
<coverType>User Guide</coverType>
<projectName>${project.name}</projectName>
<projectLogo><Path of Image></projectLogo>
<companyName>Knoldus Software LLP</companyName>
<companyLogo><Path of Image></companyLogo>
</cover>
</document>
There are several other plugins like markdown-pp and docbkx available which can also be used for conversion and documentation, pdf or book generation.
