A Practical Markdown Guide for This Website

24 Jul 2026·4 min read

Sample article: This page is a formatting reference. It can be removed after real articles have been published.

Markdown makes it possible to write structured website content without editing the layout code for every article.

This guide demonstrates the formatting elements that can be used in future projects, articles, and playground entries.

Frontmatter

The section between the two groups of hyphens at the top of a file is called frontmatter.

---
title: Example Article
description: A concise description used in listings and page metadata.
published: 2026-07-24
category: Data Engineering
tags:
  - python
  - pipelines
draft: true
lang: en
---

Common fields include:

title: the page or article title
description: a short summary
published: the publication date
updated: the latest substantial revision date
category: the broad content category
tags: more specific topics
draft: whether the entry is ready for production
lang: the content language

Use:

draft: true

while preparing an article.

Change it to:

draft: false

when the article is ready to publish.

Headings

Use headings to divide content into meaningful sections:

## Major section

### Subsection

#### Smaller subsection

The page title already comes from frontmatter, so the article body should normally begin with an ## heading rather than another # heading.

Paragraphs

Leave an empty line between paragraphs:

This is the first paragraph.

This is the second paragraph.

Without the empty line, Markdown may treat both lines as part of the same paragraph.

Emphasis

**Bold text**

*Italic text*

***Bold and italic text***

~~Strikethrough text~~

Rendered examples:

Bold text

Italic text

Bold and italic text

~~Strikethrough text~~

Links

Create an external link with:

[GitHub](https://github.com/)

Create an internal website link with:

[View my projects](/projects)

Internal links should normally begin with /.

Bullet lists

- Python
- SQL
- Terraform
- Docker

Nested lists use indentation:

- Data engineering
  - Data ingestion
  - Data transformation
  - Data quality
- Cloud engineering
  - Infrastructure as code
  - Deployment automation
  - Monitoring

Numbered lists

1. Define the problem
2. Design the architecture
3. Build the first version
4. Test the system
5. Document the results

Task lists

- [x] Create the repository
- [x] Add the logo
- [ ] Add the first real project
- [ ] Deploy the website

Rendered:

Create the repository
Add the logo
Add the first real project
Deploy the website

Blockquotes

> Reliable systems make failures visible and recoverable.

Rendered:

Reliable systems make failures visible and recoverable.

Blockquotes can be useful for quotations, notices, warnings, or important observations.

Inline code

Use single backticks around commands, filenames, variables, and short code fragments:

Run `pnpm dev` to start the development server.

Rendered:

Run pnpm dev to start the development server.

Code blocks

Use three backticks before and after a block of code.

Python

def greet(name: str) -> str:
    return f"Hello, {name}"

SQL

SELECT
    customer_id,
    COUNT(*) AS order_count,
    SUM(order_total) AS lifetime_value
FROM orders
GROUP BY customer_id
ORDER BY lifetime_value DESC;

Bash

git status
git add src/content/posts/my-article.md
git commit -m "content: add article on data modelling"
git push origin main

PowerShell

Get-ChildItem src/content/posts
pnpm exec astro build

Terraform

resource "aws_s3_bucket" "data_lake" {
  bucket = "example-data-lake"
}

JSON

{
  "project": "portfolio",
  "status": "in-progress",
  "technologies": ["Astro", "Markdown", "GitHub Pages"]
}

Tables

The source:

| Tool | Category | Purpose |
|---|---|---|
| Python | Programming | Data processing |
| SQL | Query language | Data analysis |
| Terraform | Infrastructure | Cloud provisioning |

Rendered:

Tool	Category	Purpose
Python	Programming	Data processing
SQL	Query language	Data analysis
Terraform	Infrastructure	Cloud provisioning

Keep tables reasonably narrow because wide tables can be difficult to read on mobile devices.

Images

Files placed inside public are referenced from the website root.

For example, a file stored at:

public/images/articles/example-dashboard.png

can be displayed with:

![Example analytics dashboard](/images/articles/example-dashboard.png)

The text inside square brackets is the alternative text. It should communicate the meaningful content of the image.

Good alternative text:

![Line chart showing monthly cloud costs falling from January to June](/images/articles/cloud-cost-chart.png)

Weak alternative text:

![image](/images/articles/cloud-cost-chart.png)

Existing logo example

The following image uses the website logo:

Its Markdown source is:

![Website logo](/images/logo.png)

Animated GIFs

Place a GIF inside the public directory:

public/images/articles/deployment-demo.gif

Then display it with:

![Short demonstration of the deployment workflow](/images/articles/deployment-demo.gif)

GIFs can demonstrate:

A dashboard interaction
A command-line workflow
A deployment process
A small application
A before-and-after comparison

Avoid recording passwords, API keys, email addresses, account identifiers, or private data.

Horizontal separators

Use three hyphens:

---

Rendered:

Escaping Markdown characters

Place a backslash before a special character when it should be displayed literally:

\*This text is not italic\*

Rendered:

*This text is not italic*

Collapsible content

Markdown documents can contain some HTML:

<details>
  <summary>Show implementation notes</summary>

  Additional information can go here.

</details>

Rendered:

Show implementation notes

This section contains supporting information that does not need to be visible initially.

Test HTML features locally because their appearance may depend on the website’s styling.

File naming

Use lowercase letters and hyphens:

building-a-data-pipeline.md

Avoid filenames such as:

Building A Data Pipeline Final Version!!.md

A post stored at:

src/content/posts/building-a-data-pipeline.md

will normally use a URL resembling:

/posts/building-a-data-pipeline

Recommended publishing workflow

Create the Markdown file.
Set draft: true.
Write and preview the article locally.
Check code blocks, images, and links.
Run pnpm exec astro build.
Change the entry to draft: false.
Stage the file.
Commit it with a clear message.
Push the commit to GitHub.

A suitable commit could be:

git commit -m "content: add article on data pipeline testing"

Final guidance

Use Markdown for content and reserve Astro component changes for site-wide layouts or functionality.

This keeps articles easy to write, review, version, and migrate.