It's Easy to Build: Custom docs project | Part 1 - MD to HTML
Tags: ruby, tutorial, html, markdown
Published: 2020-03-30 10:13:39

---
title: It's Easy to Build: Custom docs project | Part 1 - MD to HTML
published: true
tags: ruby, tutorial, html, markdown
canonical_url: https://blog.cdadityang.xyz/its-easy-to-build-custom-docs-project-part1/
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/05ivcqpro5tk1zrn8043.png
series: It's Easy to Build - Custom docs project
---

Hey there, Long time lurker here. This is my second post here. 😇

## Introduction

Recently, I had a task to write my documentation for all my self-projects in a separate place other than GitHub's [README](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). To accomplish this, I came across a few open-source projects like [Slate Docs](https://github.com/slatedocs/slate), [Docusaurus](https://github.com/facebook/docusaurus), to name a few. They are useful in their ways, but they didn't fit my expectations. I also wanted my docs in my [desityle](https://go.cdadityang.xyz/style) library, which is impossible to achieve from these projects.

So I decided to build my own docs project, and it's live at [Drabkirn Docs](https://go.cdadityang.xyz/docs), and it's [open-source](https://go.cdadityang.xyz/DghC). It took me a couple of days to learn things and complete this project, and in this tutorial series, I'll share my learnings as a beginner-friendly way.

For developers, writing docs is super-easy when we write it in `markdown` syntax, as writing in `HTML` will be a harrowing experience. That's why GitHub's README file looks simple clean with such a less code written in `README.md` file.

<!--kg-card-begin: markdown-->

For this problem statement, I came up with this solution:

1. I write my docs content in a markdown(MD) file.
2. The app converts the above MD file content to an HTML code.
3. We configure our app to include our desityle library, add our custom SEO tags and custom elements generation.
4. We then inject this HTML code to our `index.html` file.
5. Then build our code to minify content and push to production.

<!--kg-card-end: markdown-->

In this part 1 tutorial of this series, we'll take a very first small step to learn how to convert a markdown code to an HTML code and inject this HTML code into an HTML file. To accomplish this, we'll use the [Ruby language](https://www.ruby-lang.org/en/) and `redcarpet` gem.

## Getting Started

![It's Easy to Build: Custom docs project | Part 1 - MD to HTML](https://blog.cdadityang.xyz/content/images/2020/03/school-3518726_640.jpg)<figcaption>Image from Pixabay</figcaption>

For this tutorial, you'll need Ruby installed in your machine. You can use this [GoRails guide](https://gorails.com/setup/ubuntu/18.04) to setup ruby.

<!--kg-card-begin: markdown-->
First, create a new folder and `cd` into it:
```bash
$ mkdir mdtohtml
$ cd mdtohtml
```

Install the `redcarpet` gem:
  - First, you need to create a file named `Gemfile`
```bash
$ touch Gemfile
```
  - Then add `redcarpet` gem to this file:
```rb
# Gemfile
source 'https://rubygems.org'
git_source(:github) { |repo| "https://github.com/#{repo}.git" }

ruby '2.6.5'

gem 'redcarpet', '~> 3.5'
```

Install the dependencies:
```bash
$ bundle i
```

Now create three files:
  - `config.rb`: We'll write our ruby code logic in this file
  - `hello.md`: We'll write our markdown text in this file
  - `input.html`: The output of the converted markdown text which will be injected in this file.
```bash
$ touch config.rb
$ touch hello.md
$ touch input.html
```
<!--kg-card-end: markdown-->

## Codebase:
Let's start writing the code:

<!--kg-card-begin: markdown-->
First, open up your favorite editor and write a sample text in `hello.md` file
```md
# Hello

This is just a hello file

[Link](https://google.com)

> This is a blockquote

*This is em*

**This is bold**

## This is header 2

### This is header 3

```

Now, open the `config.rb` file and write our logic:
```rb
# First, we need to import `redcarpet` library
require 'redcarpet'

# Now let us import our `hello.md` file and `index.html` file:
## For `hello.md`, we only give READ permission, so that we don't mess
## up with our markdown file
## For `index.html` we'll give RE-WRITE permission, that means
## Everytime the code parses, it will clean this file and re-enter code
hello_md_text_file = File.open('./hello.md', 'r')
index_html_file = File.open('./index.html', 'w+')

# Now we'll initialize Redcarpet:
## For now, we'll not use any options, we'll keep this simple
md_renderer_options = {}
md_extensions = {}

md_renderer = Redcarpet::Render::HTML.new(md_renderer_options)
markdown = Redcarpet::Markdown.new(md_renderer, md_extensions)

# Read the contents of `hello.md` file and put it in `md_text` variable
md_text = hello_md_text_file.read

# convert MD to HTML, put it in `md_to_html_text` variable
md_to_html_text = markdown.render(md_text)

# Now inject this HTML content in `index.html` file
index_html_file.puts md_to_html_text

# Now, close the files
hello_md_text_file.close
index_html_file.close
```

This was simple; everything is explained in the code comments above, and to summarize:
  - We first import the `redcarpet` gem
  - Then we import the `hello.md` and `index.html` files
  - We'll then initialize `redcarpet` with no options to keep things simple.
  - We then convert our markdown text to HTML code and inject this code to `index.html` file
  - Finally, we close both the files as a good practice.

Running the script:
  - Run the script by using this command:
```bash
$ ruby config.rb
```

Now, in the `index.html` file, you'll see the MD to HTML converted code.
<!--kg-card-end: markdown-->

## Testing it:
![It's Easy to Build: Custom docs project | Part 1 - MD to HTML](https://blog.cdadityang.xyz/content/images/2020/03/test-tube-2103510_640.png)<figcaption>Image from Pixabay</figcaption>

We finished with the coding part, now let's test it out:

<!--kg-card-begin: markdown-->

Most of the modern machines have `python` installed, so we'll use `SimpleHTTPServer` to fire up our server, you can use any server:
```bash
$ python -m SimpleHTTPServer 3000
# Or any other web server
```

Now, visit `localhost:3000` or `$YOUR_IP:3000`, to the see your `index.html` file. It looks like this:  
  - ![It's Easy to Build: Custom docs project | Part 1 - MD to HTML](https://blog.cdadityang.xyz/content/images/2020/03/indexhtmlview.png)

To summarize, here is how the workflow will work from now:
  - You keep adding more content to `hello.md` file
  - Then, run the script:
```bash
$ ruby config.rb
```
  - The above command will update the `index.html` file.
  - Now, refresh your webpage, and you'll see the updated markdown to HTML code.
<!--kg-card-end: markdown-->

## Summary and conclusion

Let's take a quick look at what we learned today:

<!--kg-card-begin: markdown-->
1. First of all, I introduced myself, so don't forget to connect with me at [Twitter](https://twitter.com/cdadityang) or [elsewhere](https://cdadityang.xyz/).
2. Next, we described and understood our problem statement.
3. We then outlined a solution to our problem statement, and this tutorial is a partial solution to our big problem statement.
4. Then we saw what the prerequisites are, and we also set up and understood our file structure for this tutorial.
5. We then wrote our ruby code logic to solve our problem, i.e., converting a markdown text to HTML code and injecting it into an `index.html` file.
6. Next, we tested our `index.html` file by firing up a server.
7. We then defined what our workflow will be for adding more content to our `hello.md` file.
8. Finally, we took a quick look at this very summary...

<!--kg-card-end: markdown-->

That's it and Let there be the end. 🙏