Integrate Markdown in Django: A Step-by-Step Guide
Introduction
In this tutorial, we are going to learn how to integrate and use Markdown in Django. Very often, we need to process text in Markdown format to output HTML in our Django applications. This can be easily accomplished with the help of a few libraries.
Prerequisites
Before starting this tutorial, make sure that you have Django installed in your development environment. If not, you can install it with pip:
pip install django
Setting up a new Django project
Start by creating a new Django project. Run the following command in your Terminal:
django-admin startproject markdown_project
After creating the project, navigate into the project directory:
cd markdown_project
Installing the required library
To convert Markdown into HTML in Django, we will use the Markdown-deux library. This library will convert our markdown into HTML that can be used in our Django templates. To install Markdown-deux, run the following command in your Terminal:
pip install markdown-deux
Integrating Markdown-deux in Django
After installing Markdown-deux, we need to add it to the list of installed apps in our Django settings. Open the settings.py file and add 'markdown_deux' to INSTALLED_APPS:
INSTALLED_APPS = [
# ... other apps
'markdown_deux',
]
Using Markdown in Django views
Now, we are all set to use Markdown in our Django views. Here’s a basic example:
from django.shortcuts import render
from markdown_deux.templatetags.markdown_deux_tags import markdown_allowed
def post_detail(request, id):
post = get_object_or_404(Post, id=id)
content = markdown_allowed(post.content)
return render(request, 'blog/post_detail.html', {'content': content})
In the example above, we are getting a post by its id, converting the content into HTML with the markdown_allowed function, and passing the converted content into our post_detail.html template.
Using Markdown in Django templates
After converting markdown into HTML in our view, we can use it in our Django template. Open your post_detail.html template and add the following:
<div class="post-content">
<article class="post h-entry" itemscope itemtype="http://schema.org/BlogPosting">
<header class="post-header">
<h1 class="post-title p-name" itemprop="name headline">Golang Markdown Parsing with Blackfriday Library</h1>
<p class="post-meta"><time class="dt-published" datetime="2024-07-21T00:00:00+00:00" itemprop="datePublished">
Jul 21, 2024
</time>•
<span itemprop="author" itemscope itemtype="http://schema.org/Person">
<span class="p-author h-card" itemprop="name">Matthew Rathbone</span></span></p>
</header>
<div class="post-content e-content" itemprop="articleBody">
<h2 id="introduction-to-parsing-markdown-in-golang">Introduction to Parsing Markdown in Golang</h2>
<p>In this tutorial, we’re going to delve into how Go (or Golang) can be used to parse Markdown files. If you’re not already familiar with the Markdown syntax, I recommend <a href="https://blog.markdowntools.com/posts/markdown-table-ultimate-guide">this comprehensive guide</a>.</p>
<p>Parsing of Markdown in Golang can be accomplished using open source libraries, which will greatly simplify the process. Most libraries will output HTML which can then be styled or processed further.</p>
<p>One such library is <code class="language-plaintext highlighter-rouge">blackfriday</code>, so let’s jump in and look at how it is used.</p>
<h2 id="parsing-markdown-using-blackfriday">Parsing Markdown using Blackfriday</h2>
<p>Blackfriday library is a Markdown processor implemented in Go. It is compliant with the <a href="https://commonmark.org/">CommonMark specification</a> and also includes some GitHub-flavored markdown extensions.</p>
<p>First, we need to install the library:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>go get <span class="nt">-u</span> github.com/russross/blackfriday
</code></pre></div></div>
<p>Now let’s see how to parse markdown text into HTML:</p>
<div class="language-go highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">package</span> <span class="n">main</span>
<span class="k">import</span> <span class="p">(</span>
<span class="s">"fmt"</span>
<span class="s">"github.com/russross/blackfriday"</span>
<span class="p">)</span>
<span class="k">func</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// Markdown input as string</span>
<span class="n">input</span> <span class="o">:=</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">(</span><span class="s">`
# Golang Markdown Parsing
- Golang
- Blackfriday
- Markdown
- Parsing
`</span><span class="p">)</span>
<span class="c">// Parsing markdown to HTML</span>
<span class="n">output</span> <span class="o">:=</span> <span class="n">blackfriday</span><span class="o">.</span><span class="n">Run</span><span class="p">(</span><span class="n">input</span><span class="p">)</span>
<span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="kt">string</span><span class="p">(</span><span class="n">output</span><span class="p">))</span>
<span class="p">}</span>
</code></pre></div></div>
<p>Running the above code will return the following HTML:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><h1></span>Golang Markdown Parsing<span class="nt"></h1></span>
<span class="nt"><ul></span>
<span class="nt"><li></span>Golang<span class="nt"></li></span>
<span class="nt"><li></span>Blackfriday<span class="nt"></li></span>
<span class="nt"><li></span>Markdown<span class="nt"></li></span>
<span class="nt"><li></span>Parsing<span class="nt"></li></span>
<span class="nt"></ul></span>
</code></pre></div></div>
<h2 id="parsing-markdown-files">Parsing Markdown Files</h2>
<p>Now, let’s suppose that our Markdown input is in a file. Our goal is to parse that file and output the HTML. This will involve reading in the file as a byte slice which then can be passed to <code class="language-plaintext highlighter-rouge">blackfriday.Run</code>.</p>
<div class="language-go highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">package</span> <span class="n">main</span>
<span class="k">import</span> <span class="p">(</span>
<span class="s">"fmt"</span>
<span class="s">"github.com/russross/blackfriday"</span>
<span class="s">"io/ioutil"</span>
<span class="s">"log"</span>
<span class="p">)</span>
<span class="k">func</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// Read file contents into byte slice</span>
<span class="n">input</span><span class="p">,</span> <span class="n">err</span> <span class="o">:=</span> <span class="n">ioutil</span><span class="o">.</span><span class="n">ReadFile</span><span class="p">(</span><span class="s">"example.md"</span><span class="p">)</span>
<span class="k">if</span> <span class="n">err</span> <span class="o">!=</span> <span class="no">nil</span> <span class="p">{</span>
<span class="n">log</span><span class="o">.</span><span class="n">Fatal</span><span class="p">(</span><span class="n">err</span><span class="p">)</span>
<span class="p">}</span>
<span class="c">// Parsing markdown to HTML</span>
<span class="n">output</span> <span class="o">:=</span> <span class="n">blackfriday</span><span class="o">.</span><span class="n">Run</span><span class="p">(</span><span class="n">input</span><span class="p">)</span>
<span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="kt">string</span><span class="p">(</span><span class="n">output</span><span class="p">))</span>
<span class="p">}</span>
</code></pre></div></div>
<p>Just replace <code class="language-plaintext highlighter-rouge">example.md</code> with your markdown file, run the code, and you will get the HTML output.</p>
<h2 id="more-on-markdown-in-golang">More on Markdown in Golang</h2>
<p>While <code class="language-plaintext highlighter-rouge">blackfriday</code> is a great library for general markdown parsing, specific requirements might require other solutions. If you’re rendering markdown in various other languages/frameworks, you might want to refer to other articles on <a href="https://blog.markdowntools.com/">our blog</a> for specifics, like <a href="https://blog.markdowntools.com/posts/rendering-markdown-in-react">Markdown in React</a> or <a href="https://blog.markdowntools.com/posts/rendering-markdown-in-ruby-on-rails">Markdown in Ruby on Rails</a>.</p>
<h2 id="wrapping-up">Wrapping up</h2>
<p>That’s it. As you can see, parsing markdown in Go using the Blackfriday library is simple and straightforward. You can now use this know-how to build own Go application and process markdown effectively. Happy coding!</p>
</div><a class="u-url" href="/posts/golang-markdown-parsing" hidden></a>
</article>
</div>
?
We are outputting the content with Django’s safe filter because it’s being treated as safe HTML.
Expected output
If you run your Django server and navigate to your post detail view, you should see your post content rendered as HTML.
Conclusion
That’s how you can use Markdown in Django. Remember, this tutorial only scratches the surface of what you can do with Markdown in Django. For more advanced uses, I recommend checking out the Markdown-deux documentation.
For more information on the Markdown syntax, check out this guide to blockquotes in markdown.
Django is a trademark of the Django Software Foundation.