How to Generate Markdown in Python Using SnakeMD

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

Table of Contents

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 projectOpens in a new tab.. 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 docsOpens in a new tab.:

  • 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 issuesOpens in a new tab.. 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.

Jeremy Grifski

Jeremy grew up in a small town where he enjoyed playing soccer and video games, practicing taekwondo, and trading Pokémon cards. Once out of the nest, he pursued a Bachelors in Computer Engineering with a minor in Game Design. After college, he spent about two years writing software for a major engineering company. Then, he earned a master's in Computer Science and Engineering. Today, he pursues a PhD in Engineering Education in order to ultimately land a teaching gig. In his spare time, Jeremy enjoys spending time with his wife, playing Overwatch and Phantasy Star Online 2, practicing trombone, watching Penguins hockey, and traveling the world.

Recent Posts