This file is a quick reference for writing pages and posts in Markdown.

Markdown lets you write plain text that Eleventy turns into HTML. The goal is to keep content simple, readable, and easy to maintain.

Basic page structure

Most Markdown files for Life's Uncertain should start with front matter.

---
title: "Page or Post Title"
description: "A short description of the page or post."
layout: layouts/page.njk
permalink: /example.html
---

For posts, use something like this:

---
date: 2026-06-05T09:00:00-07:00
title: "Post Title"
excerpt: "A short summary shown on post lists."
description: "A slightly longer description for search engines and previews."
layout: layouts/page.njk
permalink: /posts/post-title.html
tags:
 - posts
 - life-lessons
---

Headings

Use headings to organize content.

# Page title

## Main section

### Smaller section

#### Even smaller section

Use only one # heading per page if your layout does not already create the page heading.

Most of the time, your post content should start with ## headings after the title.

Paragraphs

Write normal paragraphs with a blank line between them.

This is the first paragraph.

This is the second paragraph.

Do not indent normal paragraphs. Indented text may become a code block.

Italic text

Use one asterisk on each side.

*So eat dessert first.*

Result:

So eat dessert first.

Use italics for emphasis, short phrases, titles, or a line that should feel slightly softer than bold.

Bold text

Use two asterisks on each side.

**Life's Uncertain is about finding meaning, humor, perspective, and better ways to live when life does not go according to plan.**

Result:

Life's Uncertain is about finding meaning, humor, perspective, and better ways to live when life does not go according to plan.

Use bold sparingly. It works best for a strong opening sentence or an important warning.

Bold and italic

Use three asterisks on each side.

***This is bold and italic.***

Result:

This is bold and italic.

Use this rarely.

Links

Use this format:

[Link text](https://example.com)

Example:

[Visit Life's Uncertain](https://lifesuncertain.com)

Good link text tells the reader where the link goes.

Avoid vague link text like:

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

Better:

[Read the accessibility testing guide](https://example.com/accessibility-testing.html)

Images

Use this format:

![Alt text for the image](/_assets/images/example.jpg)

Example:

![Life's Uncertain logo](/_assets/images/lifes-uncertain-1_color_no_bg_1200x630_b.png)

The alt text should describe the image if the image adds meaning.

If the image is decorative, your template may need to handle that in HTML instead of Markdown.

Bulleted lists

Use hyphens for unordered lists.

- Meaning
- Humor
- Perspective
- Better ways to keep going

Use a blank line before the list.

Numbered lists

Use numbers for steps.

1. Write the draft.
2. Read it out loud.
3. Remove anything that sounds repeated.
4. Publish when it feels clear.

Numbered lists are best for instructions or ordered steps.

Blockquotes

Use a greater-than sign.

> Life is uncertain, so eat dessert first.

Result:

Life is uncertain, so eat dessert first.

Use blockquotes for quoted lines, callout-style thoughts, or short statements that should stand apart.

Code

Use backticks for inline code.

Use `permalink` to control the final page URL.

Use fenced code blocks for longer code examples.

```html
<a href="/about.html">About</a>
```

Use a language label when possible, such as html, css, js, yaml, or markdown.

Horizontal rules

Use three hyphens on their own line.

---

Use horizontal rules sparingly. Headings usually create better structure.

Escaping Markdown characters

If Markdown turns a character into formatting and you do not want that, put a backslash before it.

\*This will not become italic.\*

Common Eleventy front matter fields

title

The page or post title.

title: "What Life's Uncertain Is About"

description

A short description for search engines and previews.

description: "A personal reflection site about uncertainty, disability, accessibility, smarter living, and humor."

excerpt

A short summary used on post list pages.

excerpt: "A plain explanation of why this site exists and what it covers."

layout

The template used to render the page.

layout: layouts/page.njk

permalink

The final URL Eleventy creates.

permalink: /about.html

or:

permalink: /posts/what-lifes-uncertain-is-about.html

Only one file can use the same permalink.

tags

Tags help organize posts.

tags:
 - posts
 - accessibility
 - life-lessons

Recommended post pattern

This pattern works well for Life's Uncertain posts.

---
date: 2026-06-05T09:00:00-07:00
title: "Post Title"
excerpt: "One sentence about the post."
description: "One or two sentences describing the post."
layout: layouts/page.njk
permalink: /posts/post-title.html
tags:
 - posts
 - life-lessons
---

**Strong opening sentence.**

Short intro paragraph.

## First main section

Main idea.

## Second main section

More detail.

## The point

Short ending.

*So eat dessert first.*

Writing checklist before publishing

Before publishing, check:

• Does the title clearly say what the post is about?
• Does the opening sentence give the reader a reason to keep reading?
• Are repeated ideas removed or combined?
• Are headings useful?
• Are lists used only where they help?
• Are links descriptive?
• Do images have useful alt text?
• Is the permalink unique?
• Does the post sound like you?

Quick cleanup rules

When a draft feels repetitive:

1. Keep the strongest version of the idea.
2. Remove sentences that explain the same thing in a weaker way.
3. Combine similar paragraphs.
4. Keep the ending shorter than the beginning.
5. Read the post out loud if possible.

Useful Markdown examples

Italic tagline

*So eat dessert first.*

Strong opening

**Life's Uncertain is about finding meaning, humor, perspective, and better ways to live when life does not go according to plan.**

Short quote

> Life is uncertain. Joy should not always be postponed.

Accessible link

[Read the About page](/about.html)

Image with alt text

![Life's Uncertain logo](/_assets/images/lifes-uncertain-1_color_no_bg_1200x630_b.png)

Markdown symbols cheat sheet

Final note

Markdown should make writing easier, not more complicated.

When in doubt, use:

• Short paragraphs
• Clear headings
• Plain links
• Simple lists
• A strong opening
• A clean ending