Markdown Cells and Documentation
# CHAPTER 5
Markdown Cells and Documentation
1. Chapter Introduction
A Jupyter Notebook is not just a place to run code; it is a storytelling medium. If you hand a stakeholder a wall of raw Python code, they won't understand it. You must explain *why* you are doing what you are doing. We do this using Markdown cells. Markdown is a lightweight markup language that allows you to add formatting (bold, headers, lists) to plain text.2. Converting a Cell to Markdown
By default, new cells in Jupyter are Code cells. To write text, you must convert the cell to a Markdown cell.
- Using the Mouse: Click the dropdown in the toolbar that says "Code" and change it to "Markdown".
-
Using the Keyboard (Pro Way): Ensure you are in Command Mode (Blue Border by pressing
Esc), then pressM. (To change it back to code, pressY).
3. Headers and Typography
Markdown uses special characters to format text. When you press Shift + Enter, Jupyter renders the raw text into beautiful typography.
Headers: Use hashtags #. The more hashtags, the smaller the header.
Emphasis:
4. Lists
Unordered (Bullet) Lists: Use a dash - or an asterisk * followed by a space.
Ordered (Numbered) Lists: Use numbers followed by a period.
5. Links and Images
You can embed clickable links and display images directly in your notebook.
Hyperlinks: Display Text
Images: ! in front).*
6. Code Formatting in Markdown
Sometimes you want to talk about code inside your text without actually running it.
Inline Code: Use single backticks.
Code Blocks: Use triple backticks and specify the language for syntax highlighting. <pre>
</pre>
7. Advanced: LaTeX Math Equations
Jupyter supports LaTeX, allowing you to render beautiful mathematical equations—a critical feature for data scientists and researchers.
Wrap the math in dollar signs $.
Inline Math:
Centered Block Math: Use double dollar signs.
8. Documentation Best Practices
-
The "Newspaper" Structure: Put a large
# Titleat the very top of the notebook. Follow it with a paragraph explaining the goal of the analysis.
-
Narrative Flow: Insert a Markdown cell *before* every major block of code explaining what you are about to do. (e.g.,
"### Step 2: Removing Outliers")
- Interpret Output: Insert a Markdown cell *after* a complex chart or statistical test explaining what the business takeaway is. Don't assume the reader can interpret a p-value.
9. MCQs
How do you convert a cell to Markdown using the keyboard in Command Mode?
Which symbol is used to create a Top-Level Header (Heading 1) in Markdown?
How do you make text
What is the correct syntax for a hyperlink in Markdown?
How does the image syntax differ from the link syntax in Markdown?
What happens when you press Shift + Enter on a Markdown cell?
How do you format inline code (like mentioning a variable name) inside a Markdown sentence?
What are dollar signs $$ used for in Jupyter Markdown cells?
To create a sub-bullet point in an unordered list, you should:
How do you switch a Markdown cell back to a Python Code cell using the keyboard?
10. Interview Questions
- Q: You are handing off a Jupyter Notebook to a non-technical Business Manager. How do you structure your Markdown and code cells to ensure they understand the insights?
- Q: Write the Markdown syntax to create a level 2 header, followed by a bulleted list of three items, where the second item is bold.
11. Summary
Markdown cells elevate Jupyter from a simple code editor to a powerful documentation and storytelling platform. Use # for headers, for bold text, - for lists, and text` for links. By weaving explanatory Markdown cells between your Python Code cells, you create reproducible, easy-to-understand analytical reports.