Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 233a52a

Browse files
rasbtrasbt
committed
5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting
1 parent 689e3cf commit 233a52a

File tree

9 files changed

+357
-2
lines changed

9 files changed

+357
-2
lines changed

‎README.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,18 @@ A collection of useful scripts, tutorials, and other Python-related things
3535
- Sorting CSV files using the Python csv module [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/tutorials/sorting_csvs.ipynb)]
3636

3737

38+
<br>
39+
40+
41+
###// Python and the web
42+
43+
- 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)]
44+
45+
- 5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting [[Markdown](./tutorials/markdown_syntax_highlighting/README.md)]
46+
47+
48+
49+
3850
<br>
3951
###// benchmarks
4052

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

5365

54-
###// other
5566

56-
- 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)]
67+
68+
###// other
5769

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

‎tutorials/markdown_syntax_highlighting/README.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
[Sebastian Raschka](http://sebastianraschka.com)
2+
3+
last updated: 05/28/2014
4+
5+
<hr>
6+
I would be happy to hear your comments and suggestions.
7+
Please feel free to drop me a note via
8+
[twitter](https://twitter.com/rasbt), [email](mailto:[email protected]), or [google+](https://plus.google.com/118404394130788869227).
9+
<hr>
10+
11+
12+
# 5 simple steps for converting Markdown documents into HTML and adding Python syntax highlighting
13+
14+
<br>
15+
<br>
16+
17+
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.
18+
19+
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.
20+
21+
22+
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)
23+
24+
<br>
25+
<br>
26+
27+
##1 - Installing packages
28+
29+
The two packages that we will use are
30+
31+
- [Python-Markdown](http://pythonhosted.org/Markdown/)
32+
33+
- [Pygments](http://pygments.org)
34+
35+
Just as the name suggests, Python-Markdown is the Python package that we will use for the Markdown to HTML conversion.
36+
The second library, Pygments, will be used to add the syntax highlighting to the code blocks.
37+
Conveniently, both libraries can be installed via `pip`:
38+
39+
40+
pip install markdown
41+
42+
and
43+
44+
pip install Pygments
45+
46+
47+
(For alternative ways to install the Python-Markdown package, please see [the
48+
documentation](http://pythonhosted.org/Markdown/install.html))
49+
50+
51+
<br>
52+
<br>
53+
54+
##2 - Writing a Markdown document
55+
56+
Now, let us compose a simple Markdown document including some Python code blocks in any/our favorite Markdown editor.
57+
58+
59+
--> [**some_markdown.md**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/some_markdown.md)
60+
61+
<div style="padding:6px; color: grey; background-color: white; border: black 1px solid">
62+
<pre>
63+
64+
##This is a test
65+
66+
Code blocks must be indented by 4 whitespaces.
67+
Python-Markdown has a auto-guess function which works
68+
pretty well:
69+
70+
print("Hello, World")
71+
# some comment
72+
for letter in "this is a test":
73+
print(letter)
74+
75+
In cases where Python-Markdown has problems figuring out which
76+
programming language we use, we can also add the language-tag
77+
explicitly. One way to do this would be:
78+
79+
:::python
80+
print("Hello, World")
81+
82+
or we can highlight certain lines to
83+
draw the reader's attention:
84+
85+
:::python hl_lines="1 5"
86+
print("highlight me!")
87+
# but not me!
88+
for letter in "this is a test":
89+
print(letter)
90+
# I want to be highlighted, too!
91+
92+
</pre>
93+
</div>
94+
95+
96+
<br>
97+
<br>
98+
99+
## 3 - Converting the Markdown document to HTML
100+
101+
102+
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.
103+
104+
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).
105+
106+
The basic command line usage to convert a Markdown document into HTML would be:
107+
108+
python -m markdown input.md > output.html
109+
110+
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:
111+
112+
113+
python -m markdown -x codehilite some_markdown.md > body.html
114+
115+
This will create the HTML body with our Markdown code converted to HTML with the Python code blocks annotated for the syntax highlighting.
116+
117+
118+
<br>
119+
<br>
120+
121+
##4 - Generating the CSS
122+
123+
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.
124+
125+
![](./images/mk_syntax_body_html.png)
126+
127+
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.
128+
129+
pygmentize -S default -f html > codehilite.css
130+
131+
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
132+
133+
134+
<br>
135+
<br>
136+
137+
138+
## 5 - Insert into your HTML body
139+
140+
141+
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.
142+
143+
144+
145+
`<link rel="stylesheet" type="text/css" href="./codehilite.css">`
146+
147+
148+
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).
149+
150+
151+
[**template.html**](https://github.com/rasbt/python_reference/blob/master/tutorials/markdown_syntax_highlighting/template.html):
152+
153+
<code>
154+
155+
<!DOCTYPE html>
156+
<html lang="en">
157+
158+
<head>
159+
<meta charset="utf-8">
160+
<link rel="stylesheet" type="text/css" href="./codehilite.css">
161+
</head>
162+
163+
<body>
164+
165+
<-- converted HTML contents go here
166+
167+
</body>
168+
</html>
169+
170+
</code>
171+
172+
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.
173+
174+
![](./images/mk_syntax_final_html.png)
175+
176+

‎tutorials/markdown_syntax_highlighting/body.html‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<h2>This is a test</h2>
2+
<p>Code blocks must be indented by 4 whitespaces.
3+
Python-Markdown has a auto-guess function which works
4+
pretty well:</p>
5+
<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>
6+
<span class="cp"># some comment</span>
7+
<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>
8+
<span class="n">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
9+
</pre></div>
10+
11+
12+
<p>In cases where Python-Markdown has problems figuring out which
13+
programming language we use, we can also add the language-tag
14+
explicitly. One way to do this would be:</p>
15+
<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>
16+
</pre></div>
17+
18+
19+
<p>or we can highlight certain lines to
20+
draw the reader's attention:</p>
21+
<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>
22+
</span><span class="c"># but not me!</span>
23+
<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>
24+
<span class="k">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
25+
<span class="hll"><span class="c"># I want to be highlighted, too!</span>
26+
</span></pre></div>

‎tutorials/markdown_syntax_highlighting/codehilite.css‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.hll { background-color: #ffffcc }
2+
.c { color: #408080; font-style: italic } /* Comment */
3+
.err { border: 1px solid #FF0000 } /* Error */
4+
.k { color: #008000; font-weight: bold } /* Keyword */
5+
.o { color: #666666 } /* Operator */
6+
.cm { color: #408080; font-style: italic } /* Comment.Multiline */
7+
.cp { color: #BC7A00 } /* Comment.Preproc */
8+
.c1 { color: #408080; font-style: italic } /* Comment.Single */
9+
.cs { color: #408080; font-style: italic } /* Comment.Special */
10+
.gd { color: #A00000 } /* Generic.Deleted */
11+
.ge { font-style: italic } /* Generic.Emph */
12+
.gr { color: #FF0000 } /* Generic.Error */
13+
.gh { color: #000080; font-weight: bold } /* Generic.Heading */
14+
.gi { color: #00A000 } /* Generic.Inserted */
15+
.go { color: #888888 } /* Generic.Output */
16+
.gp { color: #000080; font-weight: bold } /* Generic.Prompt */
17+
.gs { font-weight: bold } /* Generic.Strong */
18+
.gu { color: #800080; font-weight: bold } /* Generic.Subheading */
19+
.gt { color: #0044DD } /* Generic.Traceback */
20+
.kc { color: #008000; font-weight: bold } /* Keyword.Constant */
21+
.kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
22+
.kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
23+
.kp { color: #008000 } /* Keyword.Pseudo */
24+
.kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
25+
.kt { color: #B00040 } /* Keyword.Type */
26+
.m { color: #666666 } /* Literal.Number */
27+
.s { color: #BA2121 } /* Literal.String */
28+
.na { color: #7D9029 } /* Name.Attribute */
29+
.nb { color: #008000 } /* Name.Builtin */
30+
.nc { color: #0000FF; font-weight: bold } /* Name.Class */
31+
.no { color: #880000 } /* Name.Constant */
32+
.nd { color: #AA22FF } /* Name.Decorator */
33+
.ni { color: #999999; font-weight: bold } /* Name.Entity */
34+
.ne { color: #D2413A; font-weight: bold } /* Name.Exception */
35+
.nf { color: #0000FF } /* Name.Function */
36+
.nl { color: #A0A000 } /* Name.Label */
37+
.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
38+
.nt { color: #008000; font-weight: bold } /* Name.Tag */
39+
.nv { color: #19177C } /* Name.Variable */
40+
.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
41+
.w { color: #bbbbbb } /* Text.Whitespace */
42+
.mf { color: #666666 } /* Literal.Number.Float */
43+
.mh { color: #666666 } /* Literal.Number.Hex */
44+
.mi { color: #666666 } /* Literal.Number.Integer */
45+
.mo { color: #666666 } /* Literal.Number.Oct */
46+
.sb { color: #BA2121 } /* Literal.String.Backtick */
47+
.sc { color: #BA2121 } /* Literal.String.Char */
48+
.sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
49+
.s2 { color: #BA2121 } /* Literal.String.Double */
50+
.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
51+
.sh { color: #BA2121 } /* Literal.String.Heredoc */
52+
.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
53+
.sx { color: #008000 } /* Literal.String.Other */
54+
.sr { color: #BB6688 } /* Literal.String.Regex */
55+
.s1 { color: #BA2121 } /* Literal.String.Single */
56+
.ss { color: #19177C } /* Literal.String.Symbol */
57+
.bp { color: #008000 } /* Name.Builtin.Pseudo */
58+
.vc { color: #19177C } /* Name.Variable.Class */
59+
.vg { color: #19177C } /* Name.Variable.Global */
60+
.vi { color: #19177C } /* Name.Variable.Instance */
61+
.il { color: #666666 } /* Literal.Number.Integer.Long */

‎tutorials/markdown_syntax_highlighting/final.html‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="utf-8">
6+
<link rel="stylesheet" type="text/css" href="./codehilite.css">
7+
</head>
8+
9+
<body>
10+
11+
<h2>This is a test</h2>
12+
<p>Code blocks must be indented by 4 whitespaces.
13+
Python-Markdown has a auto-guess function which works
14+
pretty well:</p>
15+
<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>
16+
<span class="cp"># some comment</span>
17+
<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>
18+
<span class="n">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
19+
</pre></div>
20+
21+
22+
<p>In cases where Python-Markdown has problems figuring out which
23+
programming language we use, we can also add the language-tag
24+
explicitly. One way to do this would be:</p>
25+
<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>
26+
</pre></div>
27+
28+
29+
<p>or we can highlight certain lines to
30+
draw the reader's attention:</p>
31+
<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>
32+
</span><span class="c"># but not me!</span>
33+
<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>
34+
<span class="k">print</span><span class="p">(</span><span class="n">letter</span><span class="p">)</span>
35+
<span class="hll"><span class="c"># I want to be highlighted, too!</span>
36+
</span></pre></div>
37+
38+
</body>
39+
</html>

‎tutorials/markdown_syntax_highlighting/images/mk_syntax_body_html.png‎

145 KB
Loading

‎tutorials/markdown_syntax_highlighting/images/mk_syntax_final_html.png‎

163 KB
Loading

‎tutorials/markdown_syntax_highlighting/some_markdown.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
##This is a test
2+
3+
Code blocks must be indented by 4 whitespaces.
4+
Python-Markdown has a auto-guess function which works
5+
pretty well:
6+
7+
print("Hello, World")
8+
# some comment
9+
for letter in "this is a test":
10+
print(letter)
11+
12+
In cases where Python-Markdown has problems figuring out which
13+
programming language we use, we can also add the language-tag
14+
explicitly. One way to do this would be:
15+
16+
:::python
17+
print("Hello, World")
18+
19+
or we can highlight certain lines to
20+
draw the reader's attention:
21+
22+
:::python hl_lines="1 5"
23+
print("highlight me!")
24+
# but not me!
25+
for letter in "this is a test":
26+
print(letter)
27+
# I want to be highlighted, too!

‎tutorials/markdown_syntax_highlighting/template.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="utf-8">
6+
<link rel="stylesheet" type="text/css" href="./codehilite.css">
7+
</head>
8+
9+
<body>
10+
11+
<-- converted HTML contents go here
12+
13+
</body>
14+
</html>

0 commit comments

Comments
 (0)