How to Generate Markdown in Python Using SnakeMD v0.x

Warning: this guide exists for historical purposes and is not up to date with the latest version of SnakeMD. If you’d like to use a guide that is up-to-date, check out our complete guide to SnakeMD. Or better yet, head over to the docs directly. However, if you are using SnakeMD v0.x, this guide will work just fine. Regardless, we would encourage you to check out the 2.0.0 migration guide, so you can use a more mature version of the library.

Recently, I wrote a Python library for creating markdown files. Now, you no longer need to roll your own. It’s time to introduce SnakeMD!

1 A Quick Overview of Markdown

2 Introducing SnakeMD

2.1 Installing SnakeMD

2.2 Creating a Markdown Document

2.3 Modifying a Markdown Document (Basic)

2.4 Modifying a Markdown Document (Advanced)

3 Plans for SnakeMD

A Quick Overview of Markdown

If you found this article, there is a good chance you’re already familiar with markdown. That said, as a quick overview, I figured I’d take a moment to explain what it is.

In essence, markdown is a programming language (yes, I said programming language) developed for quickly prototyping webpages and documents. Think of it has a stripped down version of HTML.

In general, markdown is common in a lot of places, but I’ve seen in most often on GitHub has the default README format. Similarly, I’ve seen it used in other places such as in Jekyll, which is supported by GitHub pages. As a result, there’s a good chance you’ve bumped into it before.

Most recently, I wrote about automating your GitHub profile which would involve the use of markdown. Naturally, I figured it was time to formally introduce a library I created called SnakeMD to help generate markdown using Python.

Introducing SnakeMD

If you’ve followed any of the projects we work on at The Renegade Coder, you might be familiar with the Sample Programs repo. Basically, it’s a collection of programs in as many languages as possible. In an effort to improve the experience of that collection, I had written several tools to automate various tasks related to it. For example, I wrote a tool to automate the GitHub wiki. Later, I wrote another tool to automate each language’s README.

Until recently, however, all of those tools were integrated under one repository meant for automating various tasks in the Sample Programs repo. That’s when I decided to extract the code responsible for automating the various markdown tasks into its own library: SnakeMD.

For the uninitiated, SnakeMD is an object-oriented Python library which allows a user to create and modify markdown files. In addition to being able to add the usual elements to a markdown file like headers and tables, SnakeMD also offers a few convenience features like being able to add a table of contents. To see the full range of features, check out the main README for the project. Otherwise, we’ll dive right in.

Installing SnakeMD

Like most Python packages, SnakeMD can be installed using pip. If you don’t care about cluttering your system with Python packages, you can install SnakeMD as follows:

pip install snakemd

Creating a Markdown Document

Once you have SnakeMD installed, you can create your first document as follows:

from snakemd import Document

doc = Document("Title")

In the future, we’ll probably streamline this process with code that looks as follows:

import snakemd

doc = snakemd.create_doc("Title")

Modifying a Markdown Document (Basic)

With a document created, we can now add whatever we want. Keep in mind that information is always added in the order that the `add_` functions are executed. For example, if we want to add a header and some text, we would do that as follows:

doc.add_header("Introduction")
doc.add_paragraph("My name is Jeremy")

If we were to swap these lines of code, the header would come after the paragraph. Keep that in mind!

Modifying a Markdown Document (Advanced)

In general, SnakeMD supports easy creation of markdown files through all of the convenience methods in Document. That said, sometimes you want more control. In that case, we support the `add_element()` function. Elements are considered the following standalone sections of a markdown file:

Horizontal Rules
Headers
Paragraphs
Lists
Tables

Each of these elements have their own corresponding classes which you can read more about in the docs:

HorizontalRule
Header
Paragraph
MDList
Table

Typically, you would want to take advantage of these classes if you needed to embed links in them. For example, the `add_ordered_list()` function only accepts strings. If you want to include links in any of those strings, you will need to construct the list using MDList directly. Here’s an example of what that might look like:

# items = {item: url, ...}
md_list = MDList([InlineText(item, url=url) for item, url in items.items()], ordered=True)
doc.add_element(md_list)

In this example, we have some dictionary called `items` which contains a list of items mapped to URLs. You can then convert that into an MDList using a list comprehension. The MDList is then passed to `add_element()`.

Naturally, this sort of thing can be done for all five classes, if needed.

Plans for SnakeMD

At the moment, I don’t have many plans beyond what you can see in the list of issues. That said, at the moment, I am quite pleased with where the library is at as it serves me in four of my own repos:

If you’re interested in including the library in your own projects, don’t forget to include SnakeMD in your dependencies list (e.g., requirements.txt). That way, I can show the project some love.

Otherwise, that’s all I have! While you’re here, why not check out some of the other projects I’m working on:

Thanks again for sticking around! We’ll catch you in the next one.

SnakeMD News (3 Articles)—Series Navigation

SnakeMD is a Python package that allows users to generate Markdown.

[#2]: Next Post →