This is a common experience when contributing to open source: you make a small change, open a pull request, and suddenly everything fails.

Not just one check, but multiple:

• Lint errors

• YAML validation issues

• Build failures

• Deployment failures

Even more confusing, you may see errors in parts of the codebase you didn’t modify.

In this article, you'll learn how to debug these issues step by step. The goal is not just to fix one pull request, but to understand how CI systems validate your changes.

This guide is based on a real debugging experience from contributing to an open source documentation project.

While this example comes from a documentation project, the debugging workflow applies to many repositories that use CI pipelines, linting tools, and automated builds.

Table of Contents:

• Understanding the CI Pipeline (What’s Actually Happening)

• How a CI Pipeline Processes Your Pull Request

• A Practical Debugging Workflow

  • Step 1: Fix Authentication and Permission Issues

  • Step 2: Run Lint Checks Locally

  • Step 3: Fix Common Markdown Lint Errors

  • Step 4: Fix YAML Inside Markdown Code Blocks

  • Step 5: Fix Build Errors After Lint Passes

  • Step 6: Debug Cascading CI Failures

  • Step 7: Handle Git Issues During CI Debugging

• Key Takeaways

• Conclusion

Prerequisites

To follow this guide, you should have:

• Basic familiarity with Git and pull requests

• A GitHub account

• Some exposure to CI/CD concepts (helpful but not required)

Understanding the CI Pipeline (What’s Actually Happening)

In many projects, you will see the term CI/CD, which stands for Continuous Integration and Continuous Deployment (or Delivery).

In this guide, we'll focus specifically on the CI part – that is, Continuous Integration. This refers to the automated checks that run when you push code or open a pull request. These checks validate your changes before they're merged into the main codebase.

CD (Continuous Deployment/Delivery), on the other hand, typically handles what happens after those checks pass, such as deploying the application.

Understanding this distinction is important because most of the issues we debug in this guide happen during the CI stage.

Most repositories run multiple automated checks when you open a pull request:

• Linting tools (for example, markdownlint, yamllint) enforce formatting rules

• Build systems (for example, mdBook) validate structure and generate output

• Deployment checks (for example, Netlify) ensure that the site can be built and served

• Merge controllers (for example, Tide) enforce approval policies

A key point to remember: CI systems validate the entire set of files in your commit, not just the lines you changed.

How a CI Pipeline Processes Your Pull Request

When you push code or open a pull request, the CI pipeline runs several checks in sequence.

Let’s visualize how these checks are connected in a typical CI pipeline.

Figure: A simplified CI pipeline showing how linting, build, and deployment checks are executed sequentially.

The above diagram shows a sequential CI pipeline with feedback loops, where failures at any stage return you to fix the issue before continuing.

Let’s break down what this diagram shows:

1. You start by pushing code or opening a pull request.

2. The CI pipeline begins running automated checks.

3. The first set of checks typically includes linting tools like markdownlint or yamllint.

   • If linting fails, the pipeline stops, and you must fix formatting issues before continuing.

   • If linting passes, the pipeline moves to the build step (for example, mdBook in documentation projects).

   • If the build fails, it usually means there is a structural issue, such as duplicate entries or invalid references.

4. After a successful build, deployment checks (such as Netlify previews) run.

   • If deployment fails, the issue is often related to configuration or build output.

5. If all steps pass, the pull request becomes ready for review.

A Practical Debugging Workflow

Step 1: Fix Authentication and Permission Issues

Before CI runs, your push can fail due to authentication errors.

Example error:

refusing to allow a Personal Access Token to create or update workflow

This happens because GitHub requires special permissions when your commit includes files under:

.github/workflows/

The solution is to regenerate your Personal Access Token (PAT) with:

• repo access

• workflow permission

Step 2: Run Lint Checks Locally

Relying only on CI feedback slows you down because you have to push changes and wait for the pipeline to run before seeing errors.

Running checks locally allows you to catch issues immediately before pushing your code.

In practice, you should do both:

• Run checks locally to catch errors early and reduce iteration time

• Use CI as the final validation to ensure your changes meet the repository’s standards

Think of local checks as your first line of defense, and CI as the final gate before your code is accepted.

Here's an example (Markdown linting):

npm install -g markdownlint-cli2
markdownlint-cli2 docs/**/*.md

Step 3: Fix Common Markdown Lint Errors

Here are some common issues you may encounter:

1. Non-descriptive links

Non-descriptive links like "here" don't give readers any context about where the link leads. This makes documentation harder to understand and less accessible, especially for users relying on screen readers.

Instead of writing:

[here](https://example.com)

Use descriptive text like:

[command help documentation](https://example.com)

2. Line length violations

Many projects enforce a maximum line length (often around 80 characters) to improve readability across different devices and editors.

If a line is too long, you can split it into multiple lines without changing the meaning.

To do this, break the line at natural points such as spaces between words or after punctuation. Avoid breaking words or disrupting the sentence structure.
For example:

This is a long sentence that should be split across multiple
lines to satisfy lint rules.

3. List indentation issues

List indentation errors occur when nested list items aren't aligned consistently. This can break formatting and cause linting errors.

To avoid this, just make sure you use consistent spacing (usually 2 spaces per level).

Example (incorrect):

- Item 1
 - Subitem

Correct version:

- Item 1
  - Subitem

Step 4: Fix YAML Inside Markdown Code Blocks

YAML has strict formatting rules, including proper indentation, key-value structure, and consistent spacing.

Even when YAML appears inside a markdown code block, tools like yamllint still validate its structure.

Example (incorrect):

metadata:
annotations:

Correct version:

metadata:
  annotations:
    capi.metal3.io/unhealthy: "true"

In the incorrect example, annotations is not properly nested under metadata, and no key-value pair is defined.

In the corrected version:

• annotations is properly indented under metadata

• a valid key-value pair is added (capi.metal3.io/unhealthy: "true")

This structure satisfies YAML’s requirement for proper hierarchy and formatting.

Step 5: Fix Build Errors After Lint Passes

Passing lint checks doesn't guarantee that your build will succeed.

This is because linting focuses on syntax and formatting, while the build process validates the structure and integrity of the entire project.

Build failures often occur due to issues such as:

• Duplicate entries in navigation files

• Missing or incorrectly referenced files

• Invalid configuration settings

Even if your syntax is correct, the build system ensures everything connects properly.

For example, in documentation projects using tools like mdBook, a duplicate entry in SUMMARY.md can cause the build to fail even when all files pass lint checks.

Step 6: Debug Cascading CI Failures

CI pipelines are layered. One failure can trigger multiple downstream failures.

For example, imagine a YAML indentation error:

YAML error → build fails → deploy fails → multiple checks fail

To fix this:

1. Identify the first failing step in the CI logs

2. Fix that issue

3. Re-run the pipeline

In this example, the YAML indentation error is the root cause. Once you fix the YAML formatting, the lint check passes, which allows the build to proceed and the deployment step to succeed.

This is why it is important to always fix the first failure in the pipeline rather than trying to address all errors at once.

Step 7: Handle Git Issues During CI Debugging

When working with updated branches, you may encounter:

• Diverged branches

• Rebase conflicts

• Push rejections

To resolve these issues, you typically need to update your branch using one of two approaches:

Option 1: Rebase (clean history)

git pull --rebase

Rebasing rewrites your commit history so your changes appear on top of the latest version of the branch.

Use carefully:

• Only rebase your own branches

• Avoid rebasing shared branches

Option 2: Merge (safer)

git pull --no-rebase

Merging preserves the full commit history and is safer when working with others, but it may introduce additional merge commits.

Pushing your changes safely

After updating your branch, you may need to push changes:

git push --force-with-lease

Avoid using:

git push --force

The --force option can overwrite the other contributors’ work. The --force-with-lease option is safer because it only pushes if the remote branch has not changed unexpectedly.

Key Takeaways

• CI validates your entire commit, not just the specific lines you changed

• Linting and build systems enforce different rules

• YAML inside markdown must be structurally correct

• Documentation builds can fail due to structural issues

• Running checks locally significantly reduces debugging time

Conclusion

Debugging a failing pull request isn't just about fixing syntax errors.

You also need to understand how different systems interact:

• Version control

• CI pipelines

• Linting tools

• Build processes

Once you understand how these systems work together, you can debug issues systematically instead of guessing.

The next time your pull request fails, you will know exactly where to start and how to fix it.

Debugging CI issues may feel overwhelming at first, but with a structured approach, you can turn failures into a clear path for improvement.

In this tutorial, I'll explain the Pandoc's functionalities, specifically focusing on two key areas that can significantly enhance the workflow for technical writers:

Docs and Markdown Conversions: If you write in Google Docs to leverage their collaborative writing, editing, and review features, Pandoc empowers you to convert Google Docs into markdown for publishing needs, and if you write in markdown, it helps you convert markdown to Google Docs or Microsoft Word for creating deliverables.

Merging of Multiple Docs into One: If you work in the "content as component approach", Pandoc allows you to merge multiple Google Docs into a single document with a few commands for publishing needs.

You can also create scripts to automate these processes.

Why Use Markdown for Technical Writing?

Markdown is great for technical writers because it simplifies the writing process and improves collaboration. Here's why:

Readability and Ease of Use: Markdown uses plain text symbols for formatting, making it clear and easy to learn. This lets you concentrate on writing clear content without getting caught up in styling complexities.

Platform Independence: Markdown files are plain text, allowing you to write in any text editor on any device. This flexibility provides freedom in your writing environment and eliminates software compatibility concerns.

Seamless Conversion with Free Tools: Free tools such as Pandoc offer format flexibility for markdown users, such as converting markdown to Google Docs, Word documents, or HTML, ensuring compatibility with collaborative editing needs and final deliverables. This also extends to modern workflows, where large language models generate content in markdown. You can use ChatGPT or the Gemini API for creating initial drafts, integrate them with your writing, and then use Pandoc to convert the final document to Google Docs or Microsoft Word for team editing, feedback, and creating deliverables. This streamlined workflow empowers efficient and collaborative content creation.

Version Control Friendly: Markdown's plain text nature enables seamless integration with version control systems like Git. This facilitates tracking changes, reverting to previous versions. This is particularly valuable for technical writing projects that often undergo revisions and involve multiple team members working on different sections.

Why Merge Multiple Documents into One?

Technical writing often involves creating complex documents from smaller, reusable pieces. We call these pieces "content components." These components can be individual chapters, user guides, reference articles, or any other modular unit that contributes to the final product. In other words, content components are building blocks for bigger projects.

However, writing tools such as Google Docs lack the ability to merge these components into a one document. This can be a major hurdle for projects like:

1. Technical Documentation: Building a user guide by assembling and reordering pre-written topics rather than crafting the entire document from scratch.
2. Reference Guides: Consolidating multiple articles from a knowledge base into a single, printable reference manual.
3. Book Authoring: Constructing a book by compiling individual chapters and appendices, streamlining the writing and editing process.

In all these scenarios, the need to merge content components becomes crucial for creating well-structured and efficient documentation.

How to Install Pandoc

You can install Pandoc on your system using the packages available in the releases list. The installation page has a detailed tutorial on the steps to install it on different systems.

Once Pandoc is installed, you can use it in the command line to perform different document conversion operations as explained below.

How to Convert Markdown to Word or Google Docs

To convert a markdown file to a Word document or Google Docs using Pandoc, follow these steps:

1. Open a terminal or command prompt and navigate to the directory where your markdown file is located.
2. Run the following Pandoc command to convert your markdown file to a Word document:

pandoc input.md -o output.docx

Replace input.md with the name of your input markdown file, and output.docx with the desired name of your Word document.

To convert the Docx format into Google Docs, you can upload it to Google Drive and open it in Google Docs.

With these steps, you can convert your markdown files to Word documents or Google Docs using Pandoc.

How to Convert Google Docs or Word to Markdown

In this section, I'll explain how to convert a Google Docs or Microsoft Word document into arkdown format.

While the Docs format is accepted by Pandoc, you cannot use the Google Docs URL directly with Pandoc. Therefore, you need to export the Google Doc into Docx format.

Go to File > Download > Microsoft Word (.docx) in your Google Doc to download the document in the .docx format as shown in the following image:

option to download document in .docx format

Now you'll have the Word document equivalent of the Google Docs.

To convert the Word document to markdown using Pandoc, run the following command in your terminal or command prompt:

pandoc input.docx -o output.md

Replace input.docx with the name of your Word document, and output.md with the desired name of your markdown file.

How to Merge Multiple Documents into One

To merge multiple Google Docs or Word documents into a single file using Pandoc, you can follow these two steps:

1. Convert individual documents to markdown using the Pandoc conversion command to convert each Google Doc or Word document into a separate markdown file (explained in the previous section).
2. Once you have individual markdown files, use the following Pandoc command to merge them into a single document.

pandoc file1.md file2.md -o merged_output.docx

Replace file1.md and file2.md with the names of your input markdown files. These files will be merged into one merged_output.docx.

You can use your desired output format instead of merged_output.docx based on your goals. For instance, you can create a single HTML file if you intend to publish it on the web, or use the markdown format if your publishing platform supports markdown.

This approach leverages Pandoc's strengths for format conversion and merging to achieve the desired outcome of a unified document.

For more information and helpful answers about using Pandoc, check out the Pandoc FAQs.

Conclusion

In conclusion, Pandoc is a powerful and versatile tool for technical writers, offering document conversion and merging capabilities.

With its ability to convert Google Docs into markdown and merge multiple documents into one, Pandoc streamlines the process of creating and publishing technical documentation.

However, there are some limitations to this language. In some cases, we can not add that much styling or modifications.

Luckily for us, there are five highlighting features for specific segment blocks such as notice, tip, caution, important, and warning. These are also applicable in GitHub Markdown as well.

In this article, I am going to talk about these features in detail.

Video Walkthrough

If you would like to watch a complete video with step-by-step guidelines, then you can watch the video right now!

How to Create a Note Block in Markdown

Use a Note block if you want to highlight information that users should take into account – even when they are just skimming the text.

To write any Note related segment, you need to start it with an angle bracket ( > ), and then you need to specify the highlighting block as Note with [!NOTE].

After that, you need to add an angle bracket ( > ) in each new line that you want to include in your specific Note block.

If you want to close the Note block, then remove the additional angle bracket in the new line.

> [!NOTE]
> I want the readers to read it carefully as it contains many important docs.

Output:

Note block

You see that the preview already has a nice Note related symbol.

How to Create a Tip Block in Markdown

Use a Tip block if you want to provide optional information to help a user be more successful.

To write any Tip related segment, you need to start it with an angle bracket ( > ), and then you need to specify the highlighting block as Tip with [!TIP].

After that, you need to add an angle bracket ( > ) in each new line that you want to include in your specific Tip block.

If you want to close the Tip block, then remove the additional angle bracket in the new line.

> [!TIP]
> Use the command line to detect and resolve the errors!

Output:

Tip block

You see that the preview already has a nice Tip related symbol.

How to Create a Warning Block in Markdown

Use a Warning block if you want to provide critical content that demands immediate user attention due to potential risks.

To write any Warning related segment, you need to start it with an angle bracket ( > ), and then you need to specify the highlighting block as a Warning with [!WARNING].

After that, you need to add an angle bracket ( > ) in each new line that you want to include in your specific Warning block.

If you want to close the Warning block, then remove the additional angle bracket in the new line.

> [!WARNING]
> DON'T DELETE THE `package.json` file!

Output:

Warning block

You see that the preview already has a nice Warning related symbol.

How to Create a Caution Block in Markdown

Use a caution block if you want to make users aware of the potential negative consequences of an action.

To write any Caution related segment, you need to start it with an angle bracket ( > ), and then you need to specify the highlighting block as a Warning with [!CAUTION].

After that you need to add an angle bracket ( > ) in each new line that you want to include in your specific Caution block.

If you want to close the Caution block, then remove the additional angle bracket in the new line.

> [!CAUTION]
> Don't execute the code without commenting the test cases.

Output:

Caution block

You see that the preview already has a nice Caution related symbol.

How to Create an Important Block in Markdown

Use an important block if you want to provide crucial information that is necessary for users to succeed.

To write any Important related segment, you need to start it with an angle bracket ( > ), and then you need to specify the highlighting block as a Warning with [!IMPORTANT].

After that, you need to add an angle bracket ( > ) in each new line that you want to include in your specific Important block.

If you want to close the Important block, then remove the additional angle bracket in the new line.

> [!IMPORTANT]  
> Read the contribution guideline before adding a pull request.

Output:

Important block

You see that the preview already has a nice Important related symbol.

Conclusion

Thank you for reading the entire article. I hope you have learned something new here.

If you have enjoyed the procedures step-by-step, then don't forget to let me know on Twitter/X or LinkedIn. I would appreciate it if you could endorse me for some relevant skillsets on LinkedIn. I would also recommend you to subscribe to my YouTube channel for regular programming related content.

You can follow me on GitHub as well if you are interested in open source. Make sure to check my website as well.

Thank you so much! 😀

Reference

[Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta) #16925

When writing on GitHub, you can use Markdown syntax and HTML elements to extend Markdown's functionality. You can use Markdown syntax everywhere in GitHub, such as in the README file, wiki, comments, pull requests, and when creating issues.

For every software developer, learning markdown is an essential step along the path of your career.

To enhance Markdown's basic features, GitHub added some custom functionalities and created GitHub-Flavored Markdown. With this, you can easily interact with other users in pull requests and issues by mentioning user, issue, and PR references and adding emoji.

This tutorial teaches you the basics of GitHub-Flavored Markdown so you can start using it in your projects.

All the code is available in the GitHub repository.

GitHub-Flavored Markdown Syntax

GitHub Flavored Markdown syntax is divided into two parts.

1. Basic Formatting Syntax
2. Advanced Formatting Syntax

We'll look at each one in detail below.

Basic Formatting Syntax

Basic formatting syntax applies to everyone. It contains fundamental essentials such as headings, code, images, quotes, links, and so on – things you'll need to know for writing.

1. Headings
2. Paragraphs
3. Comment
4. Styling text
5. Quotes
6. Code
7. Links
8. Images
9. Lists
10. Mentioning people and teams
11. Referencing issues and pull requests
12. Using emojis
13. Footnotes
14. Alerts

Note that the code samples mostly come from GitHub's documentation.

Headings

You can use the # symbol to create headings. One # creates an H1 heading, two create an H2 heading, and so on, like this:

# A first-level heading
## A second-level heading
### A third-level heading
#### A four-level heading
##### A five-level heading
###### A six-level heading

Paragraphs

To create paragraphs, you can use a blank line to separate one or more lines of text or paragraphs.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam est odio, commodo id diam sed, pulvinar sagittis tortor. Nam vestibulum purus eros. Sed congue, mi id pretium auctor, nibh augue iaculis arcu, eu tristique quam dolor at erat.

Quisque vel odio condimentum, mollis sem vitae, porta diam. Praesent ligula elit, condimentum eget ex sed, commodo sollicitudin sapien.


Proin volutpat faucibus nulla. Nullam eros sem, ultricies gravida nunc nec, dapibus posuere nisl. Nunc lacinia elementum turpis in pharetra. Aenean eu neque eros.

Comments

Comments are available in almost every programming language. They help developers write notes and add additional information to their code, helping other developers understand what's going on and how the code is working.

To add notes and additional information in Markdown, use the following syntax: <!--- Wrap text --->.

Here's an example:

<!-- This content will not appear in the rendered Markdown -->

Styling text

You can apply basic styles to your text, such as bold, italic, strikethrough, subscript, or superscript, to improve readability and convey your point more clearly.

1. For Bold, you can use the following syntax: **your text**
2. For italics, you can use the following syntax: *your text* or _your text_.
3. For strikethrough, you can use the following syntax: ~~your text~~
4. For subscript, you can use the following syntax: The subscript <sub> text </sub> is here.
5. For superscript, you can use the following syntax: The superscript <sup> text </sup> is here.

## Bold

**your text**

## italics

*your text*
_your text_

## strikethrough

~~your text~~

## subscript

The subscript <sub> text </sub> is here.

## superscript

The subscript <sup> text </sup> is here.

Quotes

A blockquote or quote is a sentence or paragraph formatted to let the reader know that you're quoting someone. To create a blockquote in Markdown, you can use the > symbol.

> Text that is a quote

Code

Markdown files support two types of code samples: inline and code block.

1. To add a code block in a Markdown file, use the following syntax: ``` your code ``` .
2. To add inline code to the Markdown file, use the following syntax: `your code` .

## Code Block

// ES5 syntax var multiply = function(x, y) { return x * y; };

// ES6 arrow function var multiply = (x, y) => { return x * y; };

// Or even simpler var multiply = (x, y) => x * y;

## Inline code 

JavaScript provides three different value comparison operations: strict equality using `===`, loose equality using `==`, and the `Object.is()` method.

To support code highlighting in a code block, you can add an optional language identifier after your triple backticks (like JavaScript in the example below):

## Code Block

```javascript

// ES5 syntax
var multiply = function(x, y) {
  return x * y;
};

// ES6 arrow function
var multiply = (x, y) => { return x * y; };

// Or even simpler
var multiply = (x, y) => x * y;

### Links

A markdown file divides links into two categories: **inline** and **relative**.

#### Inline links

To create an inline link in a Markdown file, wrap the link text in brackets `[ ]` followed immediately by the URL in parentheses `( )`.

```markdown
This site was built using [GitHub Pages](https://pages.github.com/).

Relative links

Relative links are defined similarly to inline links but they change in the [] section: the [] section contains the path of the file in your repository.

You use relative links to link two files: for example, to link the CONTRIBUTING file into the README file.

[Contribution guidelines](docs/CONTRIBUTING.md)

Relative links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../.:

[Contribution guidelines](../docs/CONTRIBUTING.md)

Images

To add an image in a markdown file, add a ! and then wrap the alt text in []. Then, wrap the image link with parentheses ().

It looks like this:

![Markdown](https://img.shields.io/badge/markdown-%23000000.svg?style=for-the-badge&logo=markdown&logoColor=white)

Lists

A list helps record essential information in order, which can be vital for the reader and makes it easy for people to understand and find information.

Markdown files support three types of lists:

1. Ordered list
2. Unordered list
3. Task list

Ordered list

The first type is an ordered list. To create an ordered list, start with numbers followed by periods.

1. one
2. two
3. three
4. four

Unordered list

The second type is an unordered list. To create an unordered list, use -, + or * (depending on your preference - they'll all render as an unordered list):

* First item
* Second item
* Third item
* Fourth item


- First item
- Second item
- Third item
- Fourth item

+ First item
+ Second item
+ Third item
+ Fourth item

Task list

The third type is a task list. To create a task list, list items start with a hyphen, followed by a space, followed by square brackets []. You can use an x in the bracket [x] to mark a task as complete.

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

Mentioning people and teams

Mentioning users and teams in markdown

To mention a person or team in a GitHub markdown file, type @ and write the username or team username.

## person or individual username

@officialrajdeepsingh, check out the following change.

## Team or company
The section blog theme is maintained by @frontendweb

Referencing issues and pull requests

Issues and pull requests

To mention issues and pull requests in a GitHub markdown file, type a #, then type the issue or pull request number or title. Then press either tab or enter to complete the highlighted result.

Remove the default _target blank in logo #93

Using emoji

Adding emoji in markdown.

To add an emoji to your writing, type the emoji's code between two colons. If you just type :, a list of suggested emojis on GitHub will appear.

Once you find the emoji you're looking for, press Tab or Enter to choose the highlighted result.

Don't forget to leave a star on our repository! :star:

Footnotes

To add a footnote reference, add a caret and an identifier inside brackets ([^1]) using the following syntax:

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

Alerts

Alerts are a Markdown extension based on the block quote syntax that you can use to emphasize important information.

GitHub Flavored Markdown supports five types of alerts: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]. You can use any of them:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

The Alert syntax looks like this in the browser:

Adding alert example in markdown.

Advanced Formatting Syntax

This advanced formatting syntax section contains advanced use cases, such as adding diagrams and tables, collapsed sections, mathematical expressions, and more.

1. Creating a table
2. Creating a collapsed section
3. Creating diagrams
4. Mathematical expressions

Creating a table

To create tables in Markdown, you can use pipes | and hyphens -. Hyphens are used to create a column's header, while pipes are used to separate columns.

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

The table looks like this in the browser:

Table example in markdown.

Creating a collapsed section

To create a collapsed section in a markdown file, you can use the <details> tag. This tag is an HTML element that you can easily use to extend the functionality of GitHub Flavored Markdown. Here's how it works:

<details>
  <summary>Click to here. </summary>

   ### You can add a message here

   You can add text within a collapsed section. 

   You can add an image or a code block, too.

   ```ruby
     puts "Hello World"

The collapsed syntax looks like this in the browser:

![Collapsed example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/Collapsed-in-markdown.png)
_Collapsed example in markdown._

### Creating diagrams

To add diagrams to a Markdown file, use triple backticks and wrap them inside quadruple backticks. Then, tell which identifier (Mermaid, GeoJSON, TopJSON, ASCII STL) you used for the diagram.

GitHub supports diagrams using four syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL.

1. [Mermaid](#heading-mermaid) 
2. [GeoJSON and TopoJSON](#heading-geojson-and-topojson)
3. [ASCII STL](#heading-ascii-stl)

#### Mermaid 

[Mermaid](https://mermaid.js.org) is a Markdown-inspired tool that renders text into diagrams. You can create flow charts, sequence diagrams, pie charts, and more with Mermaid.

The GitHub-flavored Markdown has extended the functionality of using Mermaid with Markdown.

You can create flow charts, sequence diagrams, pie charts, and so on inside Markdown. GitHub handles the rest of that. So how do you render diagrams on the screen?

```markdown
```mermaid
graph LR;
   A --  and --> B -- to --> C

The mermaid syntax looks like this in the browser.

![Mermaid example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/mermaid-degram.png)
_Mermaid example in markdown._

#### GeoJSON and TopoJSON

You can use [GeoJSON](https://geojson.org/) or [TopoJSON](https://github.com/topojson/topojson) to add an interactive map to a GitHub repository in a README file or GitHub Wiki.

You can use code block syntax to add an interactive map.

1. GeoJSON can create a map by specifying coordinates. To add an interactive map, use the following syntax:  ` ```geojson  your code ``` `
2. TopoJSON can create a map by specifying coordinates and shapes. To add an interactive map, use the following syntax: ` ```topojson  your code ``` `

**Example using GeoJSON:**

```markdown
```geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "properties": {
        "ID": 0
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              [-90,35],
              [-90,30],
              [-85,30],
              [-85,35],
              [-90,35]
          ]
        ]
      }
    }
  ]
}

**Example of TopJSON:**

```markdown
```topojson
{
  "type": "Topology",
  "transform": {
    "scale": [0.0005000500050005, 0.00010001000100010001],
    "translate": [100, 0]
  },
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "properties": {"prop0": "value0"},
          "coordinates": [4000, 5000]
        },
        {
          "type": "LineString",
          "properties": {"prop0": "value0", "prop1": 0},
          "arcs": [0]
        },
        {
          "type": "Polygon",
          "properties": {"prop0": "value0",
            "prop1": {"this": "that"}
          },
          "arcs": [[1]]
        }
      ]
    }
  },
  "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
}

### ASCII STL

GitHub Flavored Markdown supports STL syntax. STL syntax allows you to add interactive 3D models in markdown. You can use the following syntax: ` ```stl your code.``` `

```markdown
```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  facet normal 0.0 0.0 -1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 1.0 0.0 0.0
    endloop
  endfacet
  facet normal -1.0 0.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 0.0 1.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
  facet normal 0.577 0.577 0.577
    outer loop
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
endsolid

The STL syntax looks like this in the browser:

![STL example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/stl-example.png)
_STL example in markdown._

### Mathematical expressions

You can add mathematical expressions, such as equations, terms, formulas, and so on, to a GitHub markdown file. GitHub uses [LaTeX](https://www.cmor-faculty.rice.edu/~heinken/latex/symbols.pdf) formatted within Markdown. There are two ways to add these expressions:

1. Writing inline math expressions
2. Writing math expressions as code blocks

#### Writing inline math expressions

An inline math expression starts with `$` and ends with `$`. 

```markdown
Inline math expression example: $\sqrt{3x-1}+(1+x)^2$

The inline math syntax looks like this in the browser:

Inline math expression example

Writing math expressions as code blocks

To add a math expression's code block to the Markdown file, use the ```math code block and wrap it inside ``` backticks to display the expression as a block.

To add a math expression's code block to the Markdown file, use the ````math code block and wrap it inside triple backticks to display the expression as a block.

```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

```

The math code block syntax looks like this in the browser:

Code block math expression example

Conclusion

Markdown syntax works well in GitHub and all other central Git servers, such as GitLab, Gitea, and so on.

Different tools name their markdown differently. For example, GitHub extends markdown functionality in its own way and builds GitHub Flavored Markdown. GitLab also extends markdown functionality and builds and creates a GitLab-flavored markdown.

Markdown syntax is mostly the same in every Git service. But alerts, diagrams, and a few other features only work in GitHub Flavored Markdown.

Reference

• GitHub docs – quickstart for writing on GitHub
• GitHub docs – basic syntax
• Tutorial about rendering STL in Markdown on GitHub

Visual Studio Code (VSCode) is a popular source code editor that provides excellent support for Markdown, making it easy for developers, writers, and anyone creating textual content to use Markdown effectively.

To follow through this tutorial, you must have VSCode installed on your computer and know how to navigate it.

Importance of Using Markdown in Visual Studio Code (VSCode)

The combination of Markdown and VSCode provides a user-friendly and efficient environment for writing, editing, and formatting text, which makes it a suitable choice for developers, writers, and content creators.

The following are some of the key reasons to use markdown in VSCode:

• Markdown in VSCode supports code snippets and syntax highlighting for various programming languages, making it suitable for documenting code and technical content.
• VSCode provides a built-in preview feature that you can access by clicking the preview icon at the screen's top right corner. This allows you to see your raw markdown file alongside what it will look like when you publish it on the internet. This feature also helps you spot and fix simple mistakes as you go.
• Many project repositories on platforms like GitHub use Markdown for documentation. Getting familiar with Markdown in VSCode ensures a smooth transition when contributing to open-source projects or collaborating with teams using similar documentation standards.
• You do not need to be connected to the internet to use markdown in VSCode. You can work offline and still have access to all its features.
• For developers, you can easily push your document to GitHub using VSCode's built-in terminal. This also allows for multiple persons to review and work on the same document.

How to Create a Markdown File in VSCode

Follow the steps below to create your markdown file in VSCode:

1. Create a folder on your computer to store your documents.

An image showing you how to create a folder on the desktop page of your computer. (For windows)

2. Launch your VSCode app.

3. After launching your app, click on 'File', and then on 'Open Folder' to open the folder you just created.

An image showing you how to open your folder from the VSCode app.

4. Inside your folder, click on the file symbol and create a file that ends with '.md'(For example, First-file.md).

An image showing you how to create a file inside your folder in VSCode.

5. Press enter after typing your file name and your document page will open up. You are now all set and can start writing.

An image showing your file tab and your document page.

Markdown Syntax

Markdown syntax is a collection of symbols/annotations you add to your text to tell each word or phrase what it should be doing.

Let's go through some of the most useful markdown syntax and features.

Headers

To create headers, add the pound/hash symbol (#) in front of your text. The number of pound symbols determines the header level.

For example:

 # Header 1
 ## Header 2
 ### Header 3
 #### Header 4
 ##### Header 5
 ###### Header 6

Result:

Header 1

Header 2

Header 3

Header 4

Header 5

Header 6

Lists

There are two types of lists in Markdown, the ordered list and the unordered list. To create an ordered list, just use numbers followed by a period (like 1.). To create an unordered list, add an asterisk, a plus sign, or a hyphen in front of your text (*, + or, -) and it will start an unordered list.

For example

Ordered List
 1. First List
 2. Second List
    1. Sublist 2.1
    2. Sublist 2.2

 Unordered List
 * List 1
 * List 2
    + Sublist 1.2
    + Sublist 2.2
 - Item a
 - item b

Result

Ordered List

1. First List

2. Second List

   1. Sublist 2.1
   2. Sublist 2.2

   Unordered List

3. List 1
4. List 2
   • Sublist 1.2
   • Sublist 2.2
5. Item a
6. item b

Code

You can represent code in two ways in markdown: as inline code (like this), and as a codeblock (which you'll see below).

To create inline code, place your text within two backticks (``), for example:

`inline code`

Result:

inline code

To create a code block, enclose your code in triple backticks (```) at the beginning and end of the code block. You can also specify the programming language by adding the name of the language right after the first 3 backticks.

Here's an example:

def codeblock_example(): print("Hello world!")

Result

def codeblock_example():
    print("Hello world!")

Here's an example code block in Python:

```python
def codeblock_example():
    print("Hello world!")

Result

```python
def codeblock_example():
    print("Hello world!")

Tables

You can create a table using pipes and hyphens (| and -). The pipes divide your table into columns, while the hyphens create a horizontal line.

Here's an example of creating a basic table in Markdown:

| Header 1 | Header 2 | Header 3 | Header 4 |
| -------- | -------- | -------- | -------- |
| Row 1, Col 1 | Row 1, Col 2 |Row 1, Col 3 | Row 1, Col 4 |
| Row 2, Col 1 | Row 2, Col 2 |Row 2, Col 3 | Row 2, Col 4 |

Result:

Blockquotes

The greater than sign (>) allows you to create a blockquote. You can add this sign in front of your statement or quote and it will indent and italicize the quote to set it apart from the rest of the text.

For example:

> "The technology you use impresses no one. The experience you create with it is everything."
> Sean Gerety - UX leader

Result:

"The technology you use impresses no one. The experience you create with it is everything." Sean Gerety - UX leader

Links

You can create or add links to your document using square brackets and parentheses ([] and ()). Square brackets store the link text, while parentheses store the link URL.

For example:

[freeCodeCamp](https://www.freecodecamp.org/news/)

Result:

freeCodeCamp

The result is a clickable link that takes you to the freeCodeCamp site.

Images

Adding images to your document is similar to adding links. The only difference is, you lead with an exclamation mark in front of the brackets and parentheses.

For example:

![A cute cat image](https://hips.hearstapps.com/hmg-prod/images/cute-cat-photos-1593441022.jpg?crop=1.00xw:0.753xh;0,0.153xh&resize=1200:*)

The result is the image of a cat.

Emphasis

To emphasize text or make it italic, you can wrap it in single (for italics) or double (for bold) asterisks or underscores (* or _).

For example:

*italic* or _italic_
**bold** or __bold__

Result:

italic or italic bold or bold

As you can see above, a single asterisk and underscore give your text an italic form while a double asterisk and underscore make your text bold.

Escaping Characters

To display literal characters in markdown syntax, so they appear in your document without formatting it, you need to escape them using the backslash (\).

\_literal underscore\_

Result:

_literal underscore_

HTML

Markdown supports using HTML tags for more advanced formatting when there's a need for it.

Below are some of the ways you can use HTML tags in markdown:

• Images with HTML Attributes

<img src="image_url.jpg" alt="Alt text" width="300" height="200">

The HTML attribute within the image tag allows you to control properties like the width and height of the image.

• Styling with HTML and CSS

<span style="color:green">This is a green text.</span>

Result:

This is a green text.

You can include inline CSS styles for more advanced styling in your document.

• Embedding Videos

<iframe width="500" height="300" src="https://www.nova.com/embed/example-video" frameborder="0" allowfullscreen></iframe>

You can embed videos in your document using the iframe HTML tag. The attributes within the tag allow you to control the video properties.

Conclusion

This tutorial introduced you to using Markdown in VSCode. You learned how to initiate a Markdown file in VSCode, and you saw some common Markdown syntax. I hope you understand its importance for technical writers and content creators.

The synergy between Markdown and VSCode not only enhances productivity but also ensures a smooth transition into the world of standard documentation.

Whether you're writing technical documentation or contributing to collaborative coding efforts, you should now be equipped with a valuable skillset to help you effectively communicate and present your ideas.

You might be wondering what some of the main differences between Node and Deno are. Well, Rust is a low-level language similar to C and Java. It helps make Deno super fast, and Deno is also more secure than Node.

In this article, we will build a static markdown blog with Deno in less than five minutes. In the end, we'll deploy the markdown blog with Deno deploy.

We'll use Deno's third-party blog package created by Ryan Dahl and another contributor for the blog

With the Deno blog module, you can create a fantastic blazing-fast blog. Then you can set up and deploy the blog with two lines of code. And it takes less than five minutes to configure it.

What is markdown?

Markdown is a lightweight markup language. It helps create consistently formatted text. To start working in markdown, you need an IDE that supports markdown and you'll need to create a file with a .md extension. Markdown typically supports written documents, blogs, and so on.

Some examples of documents written in Markdown are GitHub and npm READMEs, the React.js, and many more.

The Deno blog module (Package) comes with markdown support and lets you create a static blog. This module comes with lots of features, like:

1. Markdown support.
2. Auto refresh. Any change in a markdown file automatically builds and reloads your website in the browser.
3. You can customize the header and add comments and a footer section.
4. It supports SEO, SEO markup, and an inbuilt feed (sitemap).
5. iFrames support with markdown files.
6. It has built-in Preact, TypeScript, and Tailwind CSS support.
7. It allows multiple authors
8. It has middleware and redirects pathname support
9. It comes with server-side Google Analytics support

Here's a demo of the blog we'll build and deploy:

deno blog demo

All the code is available on GitHub.

Here are the steps we'll follow:

1. How to install and setup the blog
2. How to understand the folder structure
3. How to start the local developer server
4. How to add more configuration to the blog.
5. How to deploy with Deno

How to Install and Setup the Blog

First, you'll need to install the Deno blog module. The blog module comes with the init command to create a new blog setup. It looks like this:

deno run -r --allow-read --allow-write https://deno.land/x/blog/init.ts my-deno-demo-blog-name

Create a blog setup with the deno blog module

How to Understand the Folder Structure

The beauty of Deno is that you only need a few files to start a project. For the markdown blog, you need only four files:

deno folder structure

Let's go through each file in the above folder structure:

• In the deno.jsonc file you add tasks and the importMap file. Tasks are similar to scripts in Node, and in the importMap section, you pass a JSON file that contains all your import packages from Deno.
• The import_map.json file contains imports of all packages which you need to run your project.
• The posts folder contains all markdown files.
• The main.tsx file contains all configurations for the blog module.

How to Start the Local Developer Server

After installation is complete, run the local development server with the deno task dev command.

Run deno local development server

How to Add More Configuration to the Blog

The blog module default comes with the following configuration in the main.tsx file. You can easily change blog configurations according to your requirements.

// main.tsx

import blog, { ga, redirects, h } from "blog";

blog({
  title: "My Blog",
  description: "This is my new blog.",
  // header: <header>Your custom header</header>,
  // section: <section>Your custom section</section>,
  // footer: <footer>Your custom footer</footer>,
  avatar: "https://deno-avatar.deno.dev/avatar/blog.svg",
  avatarClass: "rounded-full",
  author: "An author",

  // middlewares: [

    // If you want to set up Google Analytics, paste your GA key here.
    // ga("UA-XXXXXXXX-X"),

    // If you want to provide some redirections, you can specify them here,
    // pathname specified in a key will redirect to pathname in the value.
    // redirects({
    //  "/hello_world.html": "/hello_world",
    // }),

  // ]
});

Custom configuration

Demo of custom configuration

With custom configuration, you can make your website look however you want – even like the example above. In addition, you can quickly add more custom configurations to your blog.

For example, you can change the default header, footer, title, author, theme, custom style, links, section, and so on. Here's some code to do that:

// main.tsx

/** @jsx h */
import blog, { h } from "blog";
import { Section } from './components/Section.jsx';

blog({
  author: "Rajdeep singh",
  title: "Hello, my name is Rajdeep Singh",
  description: "Nice to meet you",
  avatar:"assets/logos/profile.jpg",
  avatarClass: "rounded-full",
  coverTextColor:"white",
  links: [
    { title: "Email", url: "mailto:officialrajdeepsingh@gmail.com" },
    { title: "GitHub", url: "https://github.com/officialrajdeepsingh" },
    { title: "Twitter", url: "https://twitter.com/Official_R_deep" },
    { title: "Linkedin", url: "https://www.linkedin.com/in/officalrajdeepsingh/" },
  ],
  lang: "en",
  favicon: "favicon.ico",
  section: <Section/>,
  theme:"auto",
  cover:"assets/logos/backgroundbanner.png",
  ogImage: {
    url: "http://localhost:8000/assets/logos/Frame.png",
    twitterCard:  "summary_large_image" 
  },
  style:".markdown-body ul, .markdown-body ol { list-style: disc !important;}"
});

Markdown files support various types of frontMatter. The most common and widely used fontMatter types are:

1. YAML: YAML is identified by opening and closing ---.
2. JSON: JSON is identified by '{' and '}'.
3. TOML: TOML is identified by opening and closing +++.

The most common frontMatter is YAML. The YAML frontMatter support markdown file is everywhere. But the Deno blog module only supports yml frontMatter.

yml front matter example

The Markdown file is divided into two sections. The first section is the header (frontMatter), and the second is the body section.

The header section contains all metadata for the article. All the metadata is written inside three dashes (---) both opening and closing – for example, post title, tag, description, publish date, and so on.

Finally, in the body section, you write your article body and explain it.

// hello-world.md

---
author : "Rajdeep Singh"
publish_date : "2020-11-10T11:42:46Z"
description : "Easy Ways Add CSS in Next.js #SeriesPart2"
og:image : "assets/images/next.js-add-css-code.jpg"
tags : ["Next.js", "Next", "Next.js Framework", "Next.js Tutorial", "React.js", "react.js tutorial"]
title : "How To Add CSS In Next js?"
allow_iframes: true
cover_html: <img src="assets/images/next.js-add-css-code.jpg" alt="How To Add CSS In Next js" />
pathname: "hello-world"
---

First blog post created with the Deno blog package. It is an amazing package you can use to create markdown blogs with Tailwind CSS. 

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/3NR9Spj0DmQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>


```javascript
console.log("hello world")

The Deno blog module supports the following YML FrontMatter fields in a markdown file:

1. author (string): The `author` contains the names of the authors. For example, `author : "Rajdeep singh , deno"`
2. publish_date(Date):  The `publish_date` is required for the article.
3. description (string): The `description` is required for the description.
4. og:image(string): The `og:image` is not required. It is used for `<meta property="og:image" content="assets/images/Title-tag-In-HTML-5.jpg">`
5. tags(string[]): The `tags` are just keywords used for SEO. They're not compulsory.
6. title(string): The `title` is required for the heading.
7. allow_iframes( boolean ): the `allow_iframes` allows you to use `iframe` HTML.
8. pathname( string ): pathname is not required. For example, `http://yourdomain.com/hello-world` after your domain `hello-world` is your pathname
9. cover_html(string): The `cover_html` contains the HTML for the blog.

author : "Rajdeep Singh , Rajvinder singh" publish_date : "2022-03-20T13:09:24Z" description : "Npm install command help to install package from npmjs.org" og:image : "assets/images/npm-init-command-1.png" tags : ["npm-test", "npm-cli", "npm install command"] title : "What is the npm install command?" allow_iframes: true pathname:"/how-is-npm-install-command" cover_html:

These are all the supported fields by YML frontMatter for markdown files:

title, author, publish_date, description, og:image, tags, allow_iframes, pathname, cover_html

This is the required field for markdown files:

title ```

Without a title filed, the blog module produces an error Uncaught TypeError: Cannot read properties of undefined (reading 'snippet').

Error: Uncaught TypeError: Cannot read properties of undefined (reading 'snippet')

How to Deploy Your Blog with Deno

The final step is to deploy our static blog in Deno. Currently, the Deno blog module only supports Deno for deployment. But Deno deploy provides a similar interface to Netlify and Vercel. So you can easily understand the dashboard if you've worked with those tools before.

To deploy a new blog on Deno, you need two things. The first is an account on Deno deploy, and the second is a GitHub account. With a GitHub repository to help manage your articles, it is a straightforward process similar to Vercel and Netlify.

Deployment steps:

Here are the steps to deploy your blog with Deno deploy (we'll go through each one in detail below):

1. First, login to your account on Deno deploy
2. Click to create a new project
3. Configure the GitHub repository and environment variables
4. Deploy the static blog

Login to your account on Deno deploy

First, go to the Deno deploy website and create a new account if you don't have one already. If you do, then login to your account.

deno deploy website

Click to create a new project

After successfully logging in, you can now access the Deno dashboard and click on the "+ new project" button.

Create a new project with deno deploy

Configure the GitHub repository and environment variables

After clicking on the new project button, you'll be redirected to the project configuration page. Your project page will look like the below. Just fill in all the details:

Fill out your new project configuration and link to GitHub

The first time click the GitHub button. After that, Deno deploys and asks for permission for a GitHub account. After granting all the permissions, your project page looks like this:

After finishing the information

1. After opening the project page, you fill in all the required information.
2. Then, in the second step, select the GitHub repository.
3. After selecting the GitHub repository, select a branch, then choose main.tsx file.
4. Give any project name, but make sure you name is in lowercase letters – for example, my-new-website. Otherwise, you'll get a capital case error.
5. Click on the environment variable and add an environment (if you have one - otherwise, skip it).

And that's it - you've done all the configuration successfully. Now click on the link button.

Deployment is finished

After deployment is finished, you'll see the website dashboard. Click on the view button to view your production-ready website.

Your website dashboard with deno looks like this after successful website deployment.

Here's a tip to help you manage all your markdown files and speed up your written work. The VS Code code editor has a free, open-source FrontMatter VS Code extension. It's a great tool to manage all your markdown files inside VS Code with the FrontMatter dashboard.

Manage markdown files with VS Code extension

Conclusion

The Deno blog module is an excellent library for creating a personal blog in five minutes and deploying it with Deno. Deno deployment is speedy. It takes less than ten seconds.

I think the Deno blog module is best for personal use because you do not need to customize many things. You only customize the header, footer, and various sections.

Thank you for reading!

References to help you setup your blog:

• https://deno.land/
• https://deno.com/deploy
• https://deno.land/x/blog
• https://deno.land/x/dotenv
• https://frontmatter.codes/

And you may know that HTML is a language used to create websites – but what does markup mean?

Markup languages are languages that use tags to define different elements within a text document. Most people are familiar with Rich Text Editors – programs that allow users to add extra formatting, images, and links to their documents.

A screenshot of the GUI of the Microsoft Word software (a Rich Text Editor).

But markup languages use tags like:

• is a paragraph tag.

• makes bold text.

There are quite a few markup languages like XML, HTML, and the topic of this article: Markdown.

Developers generally use markdown for documentation – and it is often included in most repositories. For example, I used markdown to write this article on freeCodeCamp.

So let's look at all we can do with markdown.

Disclaimer: There is no unifying body or specification to standardise markdown – just some widely accepted best practices. So your mileage might vary depending on what markdown parser you're using for this cheat sheet.

Markdown Cheat Sheet

Here are some of the most commonly used methods for manipulating text in markdown.

How to Create Headers in Markdown

There are six markdown headers, H1 thorough to H6. I'll show you how it displays visually, and also the way you create it using markdown.

H1's are the biggest and generally are the "main" headers, and each header after H1 gets smaller.

H1 tag

# H1 tag

H2 tag

## H2 tag

H3 tag

### H3 tag

H4 tag

#### H4 tag

H5 Tag

##### H5 tag

H6 tag

###### H6 tag

How to Add Typographical Emphasis in Markdown

The ways you commonly add emphasis with text are bold, italics and strikethroughs. Combining too much emphasis can make words much less clear, so choose carefully how you want to emphasize each bit of text.

There are also subscript and superscript notation that you'll use to write the names of various chemical compounds, for example. You may also use them as part of mathematical notation.

How to make text bold:

Add double asterisks around your text. It'll make that text appear bold. Like this: **Bold text**

How to make your text italic:

Add single asterisks around your text to make it appear in italics, like this: *Italics*

How to Strike through certain text:

If you want to "cross something out" in text, use the strikethrough method, like this: ~~Strike through~~.

How to Write Subscripts in Markdown

If you want to write the chemical symbol for water, for example, you can make a subscript "2" by typing H~2~0.

This results in: H<sub>2</sub>0.

How to Write Superscripts in Markdown

Say you want to write an exponent - or superscript. You do that like this: X^2^ which results in this: X<sup>2</sup>.

How to Make Lists in Markdown

There are multiple types of lists in markdown. For example, you can have ordered lists and unordered lists.

Ordered lists are commonly used when you want to follow steps in a certain order (like following a recipe: cook the chicken...serve the dish). But unordered lists work well for things that don't require sequential steps like a recipe (a shopping list, for example).

How to Make an Unordered List in Markdown

This is how the unordered list looks.

• Chili oil

• Rice

• Spring onions

And this is how you create it in markdown:

- Chili oil
- Rice
- Spring onions

How to Make an Ordered List in Markdown

This is how the ordered list looks.

1. First item

2. Second item

And this is how you create it in markdown:

1. First item 
2. Second item

How to Create Links in Markdown

The two most common ways of linking things in markdown documents is either by hyperlinks or images. Both can help make your writing much clearer and more eloquent, and should be used where appropriate.

Here's what a hyperlink in text looks like:

Kealan's site

And here's how you'd create that link in Markdown:

[Kealan's site](https://www.kealanparr.com)

You put the text you want to link in square brackets (here, "Kealan's site"), and then immediately follow them with parenthesis containing the URL.

Say you want to include an image in an article. To get it to appear like this:

You simple use the following notation:

![View of natural rock landscape formations making a valley ending in a road crossing through with a blue sky.](https://images.unsplash.com/photo-1660866838784-6c5158c0f979?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=387&q=80)

It's similar to a regular link, but you include the exclamation point before the brackets.

How to Use HTML in Markdown

You can use regular HTML in Markdown documents (depending on the parser that's being used).

So feel free to just input any valid HTML you like.

How to Add Spacing in Markdown

If you want to add a horizontal line to divide up sections of a document, you can make one like this:

By using three dashes like this:

---

How to Create Tables in Markdown

Tables come in handy in your articles. To make a table that looks like this:

Here's the notation you'd use:

| Name   | Age |
| ------ | --- |
| Kealan | 25  |
| Jake   | 28  |

The only real "gotcha" you have to be aware of when making a markdown table is that you keep the pipes (|) vertically in line. Then your markdown table will appear as above in this article. An image to make that clearer is:

A markdown table is displayed, with Name and Age as the headers and Kealan, Jake and 25 & 28 as the values.

How to Add Code and Syntax in Markdown

Adding code snippets to your markdown can be incredibly helpful if you are creating documentation for developers, for example.

The below is a very simple JavaScript example, but almost all modern programming languages are supported (with syntax highlighting and so on).

console.log('example log')

console.log('example log')

Just type the three backticks followed by the programming language and then enter to start writing your code. End the code block with three backticks.

How to Add Quotes in Markdown

When you reference someone else's work, it is expected and courteous to credit them. One easy way you can do that is by quoting them.

If you want to add quotes in markdown:

"This is a quote, from someone who is very wise" - Anonymous

Just add this symbol, which renders it like the above quote:

> "This is a quote, from someone who is very wise" - Anonymous

Conclusion

I hope this has been a useful reference for you, and that you've learned a new feature of markdown you hadn't seen before.

There are lots more features (not even counting all the HTML variations you could create), but this article has covered the most used features.

This worked, and let us complete our tasks – but why settle for less when you can create a diagram within the README file itself? Well, now you can.

On February 14th, GitHub gifted a new feature to all devlovers. Mermaid syntax is now supported by default in GitHub Markdown. This means that we can now create and edit diagrams in the native markdown file.

But first, what is Mermaid?

What is Mermaid? 🧜‍♀️

Mermaid is a tool that renders diagrams based on markdown-like text content. It helps us visualize documentation and catch it up with development by dynamically creating and modifying diagrams in the browser.

Mermaid supports various types of diagrams, such as UML diagrams, Gantt charts, Git Graphs, and User Journey Diagrams.

How Does Mermaid Work? 🤔

According to the official GitHub blog, when a code block marked as mermaid is encountered, the raw mermaid syntax in the block is passed to Mermaid.js and an iframe is generated. The iframe is injected into the page, pointing src to the Viewscreen service. Viewscreen is GitHub's internal file rendering service which is partially responsible for this whole process.

The entire process is explained well in the official announcement blog. Here's a representation of how the Mermaid code block is dynamically rendered in the browser:

rendering Mermaid code

Mermaid Demo 🧐

To integrate Mermaid in your README, you don't need to add any external thing whatsoever! You just have to make a code block with the mermaid language designation.

But don't worry – you don't need to learn a new language or script. If you have an idea about markdown and supported diagrams, you won't find it too hard to get started.

Sounds simple? Let's make a user journey diagram of me studying for exams.

In your GitHub Web, open any markdown file. Paste the below code into the write section and hit preview.

journey title Me studying for exams section Exam is announced I start studying: 1: Me Make notes: 2: Me Ask friend for help: 3: Me, Friend We study togther: 5: Me, Friend section Exam Day Syllabys is incomplete: 2: Me Give exam: 1: Me, Friend section Result Declared I passed the exam with destinction!: 5: Me Friend barely gets passing marks: 2: Friend

Don't forget to enclose it in code blocks and add mermaid at the beginning.
Like this:

When rendered, it will look something like this:

User Diagram created with Mermaid in GitHub README

Fun fact: The sequence diagram depicting the rendering Mermaid syntax above is also rendered with the new feature. You can find the code here.

Final Words 👋

Mermaid integration allows you to keep your diagrams close to the documentation, saving time and effort spent managing a separate software.

You can read the original GitHub blog here or have a look at Mermaid's official documentation.

Before We End ✨

I was inspired to write this article because I was eager to try out this feature as soon as I heard about its release. I hope you found this article helpful. I have my own personal blog where I talk about web development and my experiences.

My DMs are always open if you want to say hello. I am most active on Twitter, LinkedIn, and Showwcase. See you there!

Till then, happy documenting! 📃

You can use markdown to write content that can be conveyed in plain text. A good example would be a blog post.

In this article, you'll learn what markdown is and how to use it.

What is Markdown?

Markdown is a markup language just like HTML. We use it to parse text and convert it into a specific format. You can also think of it as a text to HTML converter tool.

Many developers like writing in markdown because it gives them fine-grained control over their text and code. We'll see how and why in the coming paragraphs.

In this guide we'll cover the following topics.

• How to create your first markdown file.
• Create a cheat sheet for markdown
• Discuss how markdown can be rendered in VS Code

Tools that Support Markdown

Markdown works in any browser even if you use a simple notepad. But there are certain tools that can help enhance your productivity by providing a real time view (of markdown and rich text) side by side.

The following are some of the tools that support working with markdown:

• VSCode (We'll cover this in this article)
• Atom
• Haroopad
• Sublime text
• MarkPad

How to Work with Markdown

Download VSCode and enable the plugin

VSCode is a text editor like notepad, but it has many more capabilities. You can also use it for coding and it supports numerous programming languages.

We'll be using VSCode to write and render markdown files.

You can download VSCode from here.

Once your download is completed, activate the below extension:

VS code extension

How to create your first markdown file

To work with markdown, simply save the text file with .md extension. After that, you'll be able to apply markdown syntax.

After creating your file and activating the plugin, the workspace should look something like this.

Markdown in action

In markdown, we use a specific syntax to denote headings, bold text, lists, and other text formatting.

You can refer to the table below for an overview of basic markdown syntax:

Simply start writing in your .md file and see the results side by side.

How to write code blocks in Markdown

There is language support available for many programming languages in VSCode.

Here are some examples of coding in different languages.

Code blocks for HTML and Bash

Code blocks for Python and JS

Escape characters in markdown

If you want the browser to ignore the syntax and retain the characters, the characters can be escaped using the backslash \.

For instance, * would not parse its succeeding characters as italics.

Practical Applications of Markdown

You can use markdown in email templates, and it is a natural fit for technical documentation.

A great example for markdown is the GitHub README.md file. There, code blocks are easily combined with well-formatted text.

Download the Markdown Cheat Sheet

I've compiled all the tips you've learned here in a cheat sheet.

You can download the cheat sheet here.

Wrapping up

By now I hope you're confident enough to write your own markdown. Once you get the hang of it, it's easy enough. Apart from being simple, it is also very powerful and widely accepted.

If you found this post helpful, share it :)

Check out my other blog posts. Let's connect on Twitter.

If you want to jump right into the code, check out the GitHub Repo here: https://github.com/lelouchB/markdown-previewer/tree/master

And here's a link to the deployed version :https://markdown-previewer.lelouch-b.now.sh/.

Now let's get started.

Prerequisites

1. Knowledge of HTML, CSS, Javascript and Bootstrap.
2. Basic knowledge of React.
3. Node and NPM installed on your local dev machine.
4. Any code editor of your choice.

If you feel like your progress is hindered because you don't know enough about these subjects, check out https://www.freecodecamp.org/learn. There are some awesome modules there that will get you started in no time.

Setup

We will build this app with the help of npx create-react-app . Create React App is an officially supported way to create single-page React applications. It offers a modern build setup with no configuration.

In your project directory run the following command in the terminal:

npx create-react-app markdown-previewer
cd markdown-previewer
npm start

Then open http://localhost:3000/ to see your app. It will look like this:

http://localhost:3000/

Now, let's see the Project Structure here:

markdown-previewer
├── README.md
├── node_modules
├── package.json
├── .gitignore
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── App.test.js
    ├── index.css
    ├── index.js
    ├── logo.svg
    └── serviceWorker.js

No configuration or complicated folder structures – only the files you need to build your app.

Now, before we proceed further, let's clean up these files:

1. Delete index.css and App.css .
2. Since we have deleted index.css and App.css , remove import './index.css'; and import './App.css';from index.js and App.js respectively.
3. Delete logo.svg and remove import logo from './logo.svg'; in App.js.
4. Inside App.js remove the function App() . We will export a class component rather than a functional component. So, change App.js to look like this:

import React from 'react';

export default class App extends React.Component{
render(){
  return (
    <div className="App">

    </div>
  );}
}

Head over to http://localhost:3000 and it will be blank now.

Design

But one more thing before we get into it… It’s always a good idea to have a plan of what you are going to build before you start typing. Especially when you're building a user interface with React.

We want to have some idea of what the interface will look like so we can know what components we need to build and what data each component will be responsible for handling.

So to begin, I have drawn a quick sketch of what the markdown-previewer app will look like. I have also labeled all of the components we will need to create:

Design

So it looks like we will need to build three primary components:

1. Title and SubHeading— This will simply display our headings and subheadings.
2. Markdown Input TextArea — This is the input texarea where the markdown we want to preview will be written.
3. Markdown Preview — This is a container with a greyish background where the output will display.

A few things to note:

1. We will have an ‘App’ component that contains everything. This is small project so it is easy to maintain all the components in a single file. But as the size of your project increases (for example, while building an e-Commerce platform), you would have to seperate components into different files and folders by their types.
2. Since this article is not about CSS and designing, I will use the React-Bootstrap library and Inline Styles. Any discussion about them will be kept short.

Inline Styles in React

When using inline styles, it means that instead of making separate CSS files, components are styled by passing the CSS properties as an Object. For example:

var divStyle = {
  color: 'white',
  backgroundImage: 'url(' + imgUrl + ')',
  WebkitTransition: 'all', // note the capital 'W' here
  msTransition: 'all' // 'ms' is the only lowercase vendor prefix
};

ReactDOM.render(<div style={divStyle}>Hello World!</div>, document.getElementById("root");

Style keys are camelCased in order to be consistent with accessing the properties on DOM nodes from JS (e.g. node.style.backgroundImage). Vendor prefixes other than ms should begin with a capital letter. This is why WebkitTransition has an uppercase "W".

The style object is then passed in the DOM component using {} . We can use run Javascript code inside our return method using {}.

Code

Okay it’s time to start writing code! If at any time you get stuck, feel free to refer to the finished app here: https://github.com/lelouchB/markdown-previewer/tree/master and https://markdown-previewer.lelouch-b.now.sh/

Installing Dependencies

Let's start by installing our project dependencies. Inside the project directory, run the following commands:

npm install react-bootstrap bootstrap 
npm install marked

Now, let's discuss them:

1. The first command installs React-Bootstrap and Bootstrap which we will use to style our project.
2. The second command installs Marked.js, which is a low-level markdown compiler for parsing markdown without caching or blocking for long periods of time. This will run the actual logic behind converting the markdown.

Before we start using React-Bootstrap inside our project, we will have to add the minified bootstrap CSS file to our index.js:

import '../node_modules/bootstrap/dist/css/bootstrap.min.css';

With this the dependencies have been installed and are ready to be used.

Headings

Our first task will be to add a heading to our React app and center align it. For that we will use Badge, a component of the React-Bootstrap library. Here are the steps to do that:

1. Import Badge to App.js. Inside App.js add the following:

import Badge from "react-bootstrap/Badge";

2. In App.js inside return and under the div with the className="App", add another div with the className="container".

import React from "react";
import Badge from "react-bootstrap/Badge";

export default class App extends React.Component {
  render() {
    return (
      <div className="App">
        <div className="container">

        </div>
      </div>
    );
  }
}

3. Next inside div with the className="container", we will add the heading as follows:

 <h1>
 <Badge className="text-align-center" variant="light">
 Markdown Previewer
</Badge>
 </h1>

4. You can now see a heading at http://localhost:3000, but it is not centered. To center the heading we will use bootstrap and enclose the above code block inside two divs.

<div className="row mt-4">
  <div className="col text-center">
    <h1>
     <Badge className="text-align-center" variant="light">
        Markdown Previewer
     </Badge>
    </h1>
  </div>
</div>

With this we have added a heading to our app.

Sub Headings

If you look at the design we're discussing above, you'll see that the next step will be to add two columns with the subheadings Markdown Input and Preview. One will contain the Input TextArea and the other the Preview.

1. First we will have to create two columns placed side by side inside our app. We will do so using bootstrap. Inside the div container, add the following:

<div className="row mt-4">
  <div className="col-md-6">
    <h2>Lorem Ipsum</h2>
  </div>

  <div className="col-md-6">
    <h2>Lorem Ipsum</h2>
  </div>
</div>;

I have used Lorem Ipsum for now, and will remove it in the next step. Columns are created using bootstrap classes, and the first div with className="row mt-4" creates a row. The m indicates margin. The t indicates top. The other two divs with className="col-md-6" create two columns.

The app will now look something like this.

2. The next step will be to add headings to these columns and center align them. This can be done by adding a div with the className="col text-center" inside that Badge, to both the divs with the className="col-md-6".

<div className="col text-center">
  <h1>
    <Badge className="text-align-center" variant="light">
    // Actual Sub Heading: This code block will be same for both columns
    </Badge>
  </h1>
</div>

3. Your App.js will now look like this:

TextArea

Next we're going to add a TextArea in our app. We will use the simple HTML <textarea> tag to do so.

1. Add another div with the classname="mark-input" and add textarea with className="input" inside it.

<div className="mark-input">
  <textarea className="input"> </textarea>
</div>;

2. Let's customize TextArea a bit. As discussed above, we will be using Inline Styles, so for that let's fist initailize an Object. All the variables will be declared inside the render() function but outside of return. For example,

render(){
 var variableOne = "Lorem Ipsum"
 var variableTwo = "Lorem Ipsum"

  return(
   // Code
   )
}

3. Here is the inputStyle object:

 var inputStyle = {
      width: "400px",
      height: "50vh",
      marginLeft: "auto",
      marginRight: "auto",
      padding:"10px"
    };

4. Let's add the inputStyle object to our textarea:

<div className="mark-input" style={inputStyle}>
<textarea
  className="input"
  style={inputStyle}></textarea>

With this we have added TextArea to our App and it will look like this:

Preview

To separate our preview from the rest of the app and to enclose it inside a container, we will follow the above process. We'll create a div inside the second columns and add a style object to it, like this:

  var outputStyle = {
      width: "400px",
      height: "50vh",
      backgroundColor: "#DCDCDC",
      marginLeft: "auto",
      marginRight: "auto",
      padding:"10px"
    };

Add the object to the div :

<div className="col-md-6">
  <div className="col text-center">
    <h4>
      <Badge className="text-align-center" variant="secondary">
        Preview
      </Badge>
    </h4>
  </div>
  <div style={outputStyle}>
  </div>
</div>

Here is how the app will look now:

We now have completed the look of our app, but it is missing its functionality, so let's add that. The process from here can be divided into three steps:

1. Taking input from TextArea.
2. Passing the input to the Marked.js library and displaying the processed data to the Preview column.

Taking Input from TextArea

We will use the state object.

State

In React, “state” is an object that represents the parts of the app that can change. Each component can maintain its own state, which lives in an object called this.state. The state object is where you store property values that belong to the component.

Simply put, if you’d like your app to do anything – if you want interactivity, adding and deleting things, logging in and out – that will involve state.

Here the value of our textarea is changing, and our state will change with it. We'll add the state object inside our class App, above the render() function.

It is best practice to initialize state inside constructor. It can work without constructor also but you should avoid that. Here is how we will initialize it with the property markdown , initially having an empty string:

export default class App extends React.Component {
constructor(props){
    super(props)
    this.state = {
      markdown: "",
    };
  }
  render(){
  // method and other code
  }
  }

In this project or in any other react projects, always initialize state inside constructor(props) and below super(props).

Typically, in React, constructors are only used for two purposes:

• Initializing local state by assigning an object to this.state.
• Binding event handler methods to an instance.

Keep in mind that Constructor is the only place where you should assign this.state directly. In all other methods, you need to use this.setState() instead.

State changes are asynchronous. For better perceived performance, React may delay it, and then update several components in a single pass. React does not guarantee that the state changes are applied immediately.

As discussed above we cannot change state directly. Instead we have to use this.setState() so let's create a method that does that and is called every time the value of textarea is changed.

  updateMarkdown(markdown) {
    this.setState({ markdown });
  }

This method is created inside the class component but above the render() function.

But we will first set the value of textarea to the markdown property in state.

<textarea className="input" style={inputStyle} value={this.state.markdown}></textarea>

Now we can add updateMarkdown() to onChange() event inside <textarea> and call it this.updateMarkdown().

<textarea
  className="input"
  style={inputStyle}
  value={this.state.markdown}
  onChange={(e) => {
    this.updateMarkdown(e.target.value);
  }}
></textarea>;

Next we can check to see if state is assigning properly by passing a Javascript code and console.log() our state.

<textarea
  className="input"
  style={inputStyle}
  value={this.state.markdown}
  onChange={(e) => {
    this.updateMarkdown(e.target.value);
  }}
>
  {console.log(this.state.markdown)}
</textarea>;

Now open your console and try writing inside textarea, and hopefully you will see the same being added to the console.

Check

With this we have successfully assigned the input of textarea to our state markdown property. Here is how your App.js will look now:

Marked.js

Marked.js is the brains behind the conversion of markdown and is very simple to use.

Importing marked, add the following just below where you imported Badge from react-bootstrap/Badge

let marked = require("marked");

To use the Marked.js library, we just have to pass the string to be converted inside the marked() function. We already have the data dynamically stored inside the state object, so it will be done like this:

marked(this.state.markdown)

Now, the next step is to actually display the converted data on the webpage. To do that we will use dangerouslySetInnerHTML, which is an attribute under DOM Elements in React. According to the official documentation:

_dangerouslySetInnerHTML_ is React’s replacement for using _innerHTML_ in the browser DOM.

This means that if in React you have to set the HTML programmatically or from an external source, you will have to use dangerouslySetInnerHTML instead of traditional innerHTML in Javascript.

In simple words using **dangerouslySetInnerHTML** you can set HTML directly from React.

While using dangerouslySetInnerHTML , you will have to pass an object with a __html key. (Note the key consists of two underscores.)

Here is how we will do that:

<div
style={outputStyle}
dangerouslySetInnerHTML={{ __html: marked(this.state.markdown) }}
>
</div>

With this we have completed our project and now you will see your Markdown Previewer in action.

Here is the complete App.js

We did it! ?

Congrats on building this React Mardown Previewer.

What next?

So, what is the future of this project? You are the future. Make your own version of Markdown Previewer, add different designs, layouts, custom functionalities. For example you could add a Reset Button to clear the textarea – it's all up to your imagination. I hope you had fun coding along.

What other projects or tutorials would you like to see ? Reach out to me on Twitter, and I'll make more tutorials! If you're inspired to add features yourself, please do share and tag me – I'd love to hear about them :)

Inline Code

You can use inline code formatting to emphasize a small command or piece of syntax within a line you’re writing.

For example, you may wish to mention JavaScript’s Array.protoype.map() method. By using inline code formatting, it is clear that this is a piece of code. You might also use it to illustrate a terminal command, like yarn install.

To use inline code formatting, simply wrap the code you wish to format in backticks. On a standard US layout QWERTY keyboard, this can be found to the left of ‘1’, and above the Tab key. More information on the location of the backtick on international keyboards is provided below.

For instance, writing Array.prototype.map() in markdown will render as Array.prototype.map().

Code Blocks

To write longer or more detailed snippets of code, it is often better to place them inside a code block. Code blocks allow you to use multiple lines, and markdown will render it inside its own box and with code type font.

To achieve this, start your block with a line of three backticks. This signals to markdown that you are creating a code block. You will need to finish with another line of three backticks. For example:

var add2 = function(number) {  
   return number + 2;  
}

will render in markdown as:

var add2 = function(number) {
  return number + 2;
}

Syntax highlighting

While not supported natively by markdown, many markdown engines, including the one used by GitHub, will support syntax highlighting. This means that by telling markdown what language you're using inside the code block, it will add colors like an IDE would.

You can do this by adding the name of the language on the same line as your opening three back ticks. In the example above, if instead of the first line being you could writejs, then JavaScript highlighting will be applied to the block.

var add2 = function(number) {
    return number + 2;
}

Syntax highlighting can be applied to more than just JavaScript, though. You can use ```html:

<div class="row">
  <div class="col-md-6 col-md-offset-3">
    <h1>Hello World</h1>
  </div>
</div>

```ruby
"Hello World".split('').each do |letter|
  puts letter
end

or ```python:

a, b = 0, 1
while b < 10:
    print(b)
    a, b = a, a + b

Just remember, not all markdown engines will apply syntax highlighting.

Backticks on international keyboards

The location of the backtick key can be different on different keyboards, and if you’re not using a US layout QWERTY keyboard, it may be tricky to find. This helpful guide lists some of the ways to find your backtick key, which we’ve collected here below:

QWERTY and QWERTZ:

AZERTY: