5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting

2024-11-23 20:11:13 +00:00 · 2014-05-28 13:32:07 -04:00 · 2014-05-28 13:32:07 -04:00 · 233a52ae99
commit 233a52ae99
parent 689e3cf377
9 changed files with 357 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -35,6 +35,18 @@ A collection of useful scripts, tutorials, and other Python-related things
 - Sorting CSV files using the Python csv module [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/tutorials/sorting_csvs.ipynb)]


+<br>
+
+
+###// Python and the web
+
+- Creating a table of contents with internal links in IPython Notebooks and Markdown documents [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/tutorials/table_of_contents_ipython.ipynb)]  
+
+- 5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting [[Markdown](./tutorials/markdown_syntax_highlighting/README.md)] 
+
+
+
+
 <br>
 ###// benchmarks

@ -51,9 +63,9 @@ GitHub repository [One-Python-benchmark-per-day](https://github.com/rasbt/One-Py
 <br>


-###// other

- Creating a table of contents with internal links in IPython Notebooks and Markdown documents [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/tutorials/table_of_contents_ipython.ipynb)]   
+
+###// other 

 - Happy Mother's Day [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/funstuff/happy_mothers_day.ipynb?create=1)]

--- a/tutorials/markdown_syntax_highlighting/README.md
+++ b/tutorials/markdown_syntax_highlighting/README.md
@ -0,0 +1,176 @@
+[Sebastian Raschka](http://sebastianraschka.com)  
+
+last updated: 05/28/2014
+
+<hr>
+I would be happy to hear your comments and suggestions.  
+Please feel free to drop me a note via
+[twitter](https://twitter.com/rasbt), [email](mailto:bluewoodtree@gmail.com), or [google+](https://plus.google.com/118404394130788869227).
+<hr>
+
+
+# 5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting
+
+<br>
+<br>
+
+In this little tutorial, I want to show you in 5 simple steps how easy it is to add code syntax highlighting to your blog articles. 
+
+There are more sophisticated approaches using static site generators, e.g., [nikola](https://github.com/getnikola/nikola), but the focus here is to give you the brief introduction of how it generally works.
+
+
+All the files I will be using as examples in this tutorial can be download from the GitHub repository [/rasbt/python_reference/tutorials/markdown_syntax_highlighting](https://github.com/rasbt/python_reference/tutorials/markdown_syntax_highlighting)
+
+<br>
+<br>
+
+##1 - Installing packages
+
+The two packages that we will use are
+
+- [Python-Markdown](http://pythonhosted.org/Markdown/)
+
+- [Pygments](http://pygments.org)
+
+Just as the name suggests, Python-Markdown is the Python package that we will use for the Markdown to HTML conversion. 
+The second library, Pygments, will be used to add the syntax highlighting to the code blocks.  
+Conveniently, both libraries can be installed via `pip`:
+
+
+	pip install markdown
+	
+and
+
+	pip install Pygments
+
+
+(For alternative ways to install the Python-Markdown package, please see [the
+documentation](http://pythonhosted.org/Markdown/install.html))
+	
+
+<br>
+<br>
+
+##2 - Writing a Markdown document
+
+Now, let us compose a simple Markdown document including some Python code blocks in any/our favorite Markdown editor. 
+
+
+--> [**some_markdown.md**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/some_markdown.md)
+
+<div style="padding:6px; color: grey; background-color: white; border: black 1px solid">
+<pre>
+
+##This is a test
+
+Code blocks must be indented by 4 whitespaces.
+Python-Markdown has a auto-guess function which works
+pretty well:
+
+    print("Hello, World")
+	# some comment
+    for letter in "this is a test":
+        print(letter)
+
+In cases where Python-Markdown has problems figuring out which
+programming language we use, we can also add the language-tag
+explicitly. One way to do this would be:
+
+    :::python
+    print("Hello, World")
+
+or we can highlight certain lines to 
+draw the reader's attention:
+
+    :::python hl_lines="1 5"
+	print("highlight me!")
+	# but not me!
+    for letter in "this is a test":
+        print(letter)   
+    # I want to be highlighted, too!
+         
+</pre>  
+</div>
+
+ 
+<br>
+<br> 
+ 
+## 3 - Converting the Markdown document to HTML 
+ 
+
+After we created our Markdown document, we are going to use Python-Markdown directly from the command line to convert it into an HTML document.
+ 
+Note that we can also import Python-Markdown as a module in our Python scripts, and it comes with a rich repertory of different functions, which are [listed in the library reference](https://pythonhosted.org/Markdown/reference.html).  
+ 
+The basic command line usage to convert a Markdown document into HTML would be:
+
+	python -m markdown input.md > output.html
+	
+However, since we want to have syntax highlighting for our Python code, we will use Python-Markdown's [CodeHilite extension](http://pythonhosted.org/Markdown/extensions/code_hilite.html) by providing an additional `-x codehilite` argument on the command line:  
+
+
+	python -m markdown -x codehilite some_markdown.md > body.html
+ 
+This will create the HTML body with our Markdown code converted to HTML with the Python code blocks annotated for the syntax highlighting.
+
+
+<br>
+<br>
+
+##4 - Generating the CSS   
+
+If we open the [**body.html**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/body.html) file now, which we have created in the previous section, we will notice that it doesn't have the Python code colored yet.
+
+![](./images/mk_syntax_body_html.png)
+
+What is missing is the CSS code for adding the colors to our annotated Python code block. But we can simply create such a CSS file via `Pygments` from the command line.
+ 
+	pygmentize -S default -f html > codehilite.css  
+	
+Note that we usually only need to create the [**codehilite.css**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/codehilite.css) file once and insert a link in all our HTML files that we created via Python-Markdown to get the syntax coloring
+
+ 
+<br>
+<br> 
+ 
+ 
+## 5 - Insert into your HTML body
+ 
+
+In order to include a link to the [codehilite.css](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/codehilite.css) file for syntax coloring in our converted HTML file, we have to add the following line to the header section. 
+
+
+
+`<link rel="stylesheet" type="text/css" href="./codehilite.css">`
+
+
+Now, we can insert the HTML body ([body.html](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/body.html)), which was created from our Markdown document, directly into our final HTML file (e.g., our blog article template).
+
+
+[**template.html**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/template.html): 
+ 
+<code>
+	
+	<!DOCTYPE html>
+	<html lang="en">
+
+	<head>
+	<meta charset="utf-8">
+	<link rel="stylesheet" type="text/css" href="./codehilite.css">
+	</head>
+
+	<body>
+
+	<-- converted HTML contents go here
+
+	</body>
+	</html>
+
+</code> 
+
+If we open our [**final.html**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/template.html) file in our web browser now, we can the pretty Python syntax highlighting.
+
+![](./images/mk_syntax_final_html.png)
+
+
--- a/tutorials/markdown_syntax_highlighting/body.html
+++ b/tutorials/markdown_syntax_highlighting/body.html
@ -0,0 +1,26 @@
+<h2>This is a test</h2>
+<p>Code blocks must be indented by 4 whitespaces.
+Python-Markdown has a auto-guess function which works
+pretty well:</p>
+<div class="codehilite"><pre><span class="n">print</span><span class="p">(</span><span class="s">&quot;Hello, World&quot;</span><span class="p">)</span>
+<span class="cp"># some comment</span>
+<span class="k">for</span> <span class="n">letter</span> <span class="n">in</span> <span class="s">&quot;this is a test&quot;</span><span class="o">:</span>
+    <span class="n">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
+</pre></div>
+
+
+<p>In cases where Python-Markdown has problems figuring out which
+programming language we use, we can also add the language-tag
+explicitly. One way to do this would be:</p>
+<div class="codehilite"><pre><span class="k">print</span><span class="p">(</span><span class="s">&quot;Hello, World&quot;</span><span class="p">)</span>
+</pre></div>
+
+
+<p>or we can highlight certain lines to 
+draw the reader's attention:</p>
+<div class="codehilite"><pre><span class="hll"><span class="k">print</span><span class="p">(</span><span class="s">&quot;highlight me!&quot;</span><span class="p">)</span>
+</span><span class="c"># but not me!</span>
+<span class="k">for</span> <span class="n">letter</span> <span class="ow">in</span> <span class="s">&quot;this is a test&quot;</span><span class="p">:</span>
+    <span class="k">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>   
+<span class="hll"><span class="c"># I want to be highlighted, too!</span>
+</span></pre></div>
--- a/tutorials/markdown_syntax_highlighting/codehilite.css
+++ b/tutorials/markdown_syntax_highlighting/codehilite.css
@ -0,0 +1,61 @@
+.hll { background-color: #ffffcc }
+.c { color: #408080; font-style: italic } /* Comment */
+.err { border: 1px solid #FF0000 } /* Error */
+.k { color: #008000; font-weight: bold } /* Keyword */
+.o { color: #666666 } /* Operator */
+.cm { color: #408080; font-style: italic } /* Comment.Multiline */
+.cp { color: #BC7A00 } /* Comment.Preproc */
+.c1 { color: #408080; font-style: italic } /* Comment.Single */
+.cs { color: #408080; font-style: italic } /* Comment.Special */
+.gd { color: #A00000 } /* Generic.Deleted */
+.ge { font-style: italic } /* Generic.Emph */
+.gr { color: #FF0000 } /* Generic.Error */
+.gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.gi { color: #00A000 } /* Generic.Inserted */
+.go { color: #888888 } /* Generic.Output */
+.gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.gs { font-weight: bold } /* Generic.Strong */
+.gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.gt { color: #0044DD } /* Generic.Traceback */
+.kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
+.kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
+.kp { color: #008000 } /* Keyword.Pseudo */
+.kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.kt { color: #B00040 } /* Keyword.Type */
+.m { color: #666666 } /* Literal.Number */
+.s { color: #BA2121 } /* Literal.String */
+.na { color: #7D9029 } /* Name.Attribute */
+.nb { color: #008000 } /* Name.Builtin */
+.nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.no { color: #880000 } /* Name.Constant */
+.nd { color: #AA22FF } /* Name.Decorator */
+.ni { color: #999999; font-weight: bold } /* Name.Entity */
+.ne { color: #D2413A; font-weight: bold } /* Name.Exception */
+.nf { color: #0000FF } /* Name.Function */
+.nl { color: #A0A000 } /* Name.Label */
+.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.nt { color: #008000; font-weight: bold } /* Name.Tag */
+.nv { color: #19177C } /* Name.Variable */
+.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.w { color: #bbbbbb } /* Text.Whitespace */
+.mf { color: #666666 } /* Literal.Number.Float */
+.mh { color: #666666 } /* Literal.Number.Hex */
+.mi { color: #666666 } /* Literal.Number.Integer */
+.mo { color: #666666 } /* Literal.Number.Oct */
+.sb { color: #BA2121 } /* Literal.String.Backtick */
+.sc { color: #BA2121 } /* Literal.String.Char */
+.sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
+.s2 { color: #BA2121 } /* Literal.String.Double */
+.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
+.sh { color: #BA2121 } /* Literal.String.Heredoc */
+.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
+.sx { color: #008000 } /* Literal.String.Other */
+.sr { color: #BB6688 } /* Literal.String.Regex */
+.s1 { color: #BA2121 } /* Literal.String.Single */
+.ss { color: #19177C } /* Literal.String.Symbol */
+.bp { color: #008000 } /* Name.Builtin.Pseudo */
+.vc { color: #19177C } /* Name.Variable.Class */
+.vg { color: #19177C } /* Name.Variable.Global */
+.vi { color: #19177C } /* Name.Variable.Instance */
+.il { color: #666666 } /* Literal.Number.Integer.Long */
--- a/tutorials/markdown_syntax_highlighting/final.html
+++ b/tutorials/markdown_syntax_highlighting/final.html
@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" type="text/css" href="./codehilite.css">
+</head>
+
+<body>
+
+<h2>This is a test</h2>
+<p>Code blocks must be indented by 4 whitespaces.
+Python-Markdown has a auto-guess function which works
+pretty well:</p>
+<div class="codehilite"><pre><span class="n">print</span><span class="p">(</span><span class="s">&quot;Hello, World&quot;</span><span class="p">)</span>
+<span class="cp"># some comment</span>
+<span class="k">for</span> <span class="n">letter</span> <span class="n">in</span> <span class="s">&quot;this is a test&quot;</span><span class="o">:</span>
+    <span class="n">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
+</pre></div>
+
+
+<p>In cases where Python-Markdown has problems figuring out which
+programming language we use, we can also add the language-tag
+explicitly. One way to do this would be:</p>
+<div class="codehilite"><pre><span class="k">print</span><span class="p">(</span><span class="s">&quot;Hello, World&quot;</span><span class="p">)</span>
+</pre></div>
+
+
+<p>or we can highlight certain lines to 
+draw the reader's attention:</p>
+<div class="codehilite"><pre><span class="hll"><span class="k">print</span><span class="p">(</span><span class="s">&quot;highlight me!&quot;</span><span class="p">)</span>
+</span><span class="c"># but not me!</span>
+<span class="k">for</span> <span class="n">letter</span> <span class="ow">in</span> <span class="s">&quot;this is a test&quot;</span><span class="p">:</span>
+    <span class="k">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>   
+<span class="hll"><span class="c"># I want to be highlighted, too!</span>
+</span></pre></div>
+
+</body>
+</html>
--- a/tutorials/markdown_syntax_highlighting/images/mk_syntax_body_html.png
+++ b/tutorials/markdown_syntax_highlighting/images/mk_syntax_body_html.png
--- a/tutorials/markdown_syntax_highlighting/images/mk_syntax_final_html.png
+++ b/tutorials/markdown_syntax_highlighting/images/mk_syntax_final_html.png
--- a/tutorials/markdown_syntax_highlighting/some_markdown.md
+++ b/tutorials/markdown_syntax_highlighting/some_markdown.md
@ -0,0 +1,27 @@
+##This is a test
+
+Code blocks must be indented by 4 whitespaces.
+Python-Markdown has a auto-guess function which works
+pretty well:
+
+    print("Hello, World")
+    # some comment
+    for letter in "this is a test":
+        print(letter)
+
+In cases where Python-Markdown has problems figuring out which
+programming language we use, we can also add the language-tag
+explicitly. One way to do this would be:
+
+    :::python
+    print("Hello, World")
+
+or we can highlight certain lines to 
+draw the reader's attention:
+
+    :::python hl_lines="1 5"
+    print("highlight me!")
+    # but not me!
+    for letter in "this is a test":
+        print(letter)   
+    # I want to be highlighted, too!
--- a/tutorials/markdown_syntax_highlighting/template.html
+++ b/tutorials/markdown_syntax_highlighting/template.html
@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" type="text/css" href="./codehilite.css">
+</head>
+
+<body>
+
+<-- converted HTML contents go here
+
+</body>
+</html>