Effective way of Documentation : Markdowns and Converters


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.

Happy Reading !

References:

1. https://maven.apache.org/doxia/

2. https://github.com/walokra/markdown-page-generator-plugin

3. http://maven.apache.org/plugins/maven-pdf-plugin/

Advertisements
This entry was posted in Scala. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s