Motivation: Why use Markdown with Python?

Motivation: Why use Markdown with Python?#

Learning Objectives#

  • Explain what markup languages are

  • Describe what Markdown is and why we would want to use it

  • Understand the benefits of embedding Python code in Markdown

What is a Markup language?#

A markup language is a system for annotating text so that it can be formatted and structured when displayed. Unlike programming languages, which execute commands, markup languages are used to define the appearance and structure of text in documents, web pages, and other digital formats.

How Markup Languages Work#

Markup languages use tags or symbols to indicate formatting elements such as headings, bold text, links, and lists. These annotations do not appear in the final document but determine how content is displayed. Popular markup languages include HTML, XML, Markdown and Latex. They each have their own benefits and use cases. In this course we will be focusing on Markdown.

What is Markdown?#

Markdown is a lightweight markup language that allows you to format text using a simple syntax. It is widely used for writing documentation, README files and technical papers because it is easy to read and write. These course materials are written in Markdown.

Unlike traditional word processing formats, Markdown is plain text, making it highly portable and compatible with version control systems like Git.

Why Use Markdown?#

Markdown offers several benefits:

  • Simplicity: Its syntax is easy to learn and use.

  • Readability: Even without being rendered, Markdown files remain highly readable.

  • Portability: It is supported across various platforms and can be converted to formats like HTML and PDF.

  • Integration: Many platforms, including GitHub, Jupyter Notebooks, and documentation generators, support Markdown natively.

Embedding Python Code in Markdown#

A powerful feature of using Markdown is its ability to embed and highlight code snippets. Markdown can do this for a variety of different programming languages and in this course, we will be demonstrating this with Python.

The benefits of embedding Python Code in Markdown#

Here are some of the reasons why using Markdown with Python for your research and code development could enhance your work.

  • Readability and Clarity. When integrating Markdown with environments like Jupyter Notebooks, you will be able to display your code and research in a structured and readable format. You can use it to present text, tables, code, equations and images. This is particularly useful when writing documentation for your software or communicating research results to your peers.

  • Reproducibility and Research. For data science, machine learning, and research, embedding Python in Markdown allows researchers to present their explanations and findings alongside the actual code. This is helpful when understanding the logic behind the code is as important as the code itself. It also ensures that code, results, and explanations are all in one place, and importantly, facilitates reproducibility, allowing others to verify and build upon the work.

  • Code Execution and Outputs. In environments like Jupyter Notebooks, Markdown is not just for formatting — it also allows for live interactions and executing code. Being able to contain explanations and visualizations alongside live code execution can be useful for data storytelling, where results are immediately visible after execution.

Contents