Writing Guide | Digital Garden

What Is This Guide?

This note is a living reference for writing notes in this digital garden. It covers standard Markdown, Obsidian-specific features, and the frontmatter fields available to you. Everything you see below is rendered from the raw source — so you can copy any pattern directly.

Frontmatter

Every note must begin with a YAML frontmatter block between --- fences. Here are all the supported fields:

---
title: "Your Note Title"
description: "A one-line summary shown in cards and SEO."
date: 2025-02-11
updated: 2025-06-15          # optional — last meaningful edit
tags: [topic, subtopic]
lang: en                      # en or fa
aliases: [alt-name, other]    # alternative names for wikilink resolution
growth: seedling              # seedling | budding | evergreen
featured: false               # true to pin on homepage
draft: false                  # true to hide from the site
image: ./my-cover.jpg         # optional — colocated cover image (relative path)
imageAlt: "Descriptive text"  # optional — alt text for cover (defaults to title)
---

Required Fields

Field	Description
`title`	Display title of the note
`date`	Creation or publish date (`YYYY-MM-DD`)
`tags`	Array of tags for filtering and discovery
`lang`	Language code — `en` or `fa`

Optional Fields

Field	Default	Description
`description`	—	Short summary for cards, search, and SEO
`updated`	—	Date of last meaningful update
`aliases`	`[]`	Alternative names that resolve `[[wikilinks]]` to this note
`growth`	`seedling`	Maturity stage of the note
`featured`	`false`	Pin the note on the homepage
`draft`	`false`	Hide from all listings and pages
`image`	—	Cover image — use relative path to a colocated file (e.g. `./cover.jpg`)
`imageAlt`	title	Descriptive alt text for the cover image (accessibility & SEO)

Growth Stages

Notes evolve over time. Use the growth field to signal maturity:

🌱 seedling — Rough idea, just planted
🌿 budding — Taking shape, still developing
🌳 evergreen — Polished and stable

Basic Markdown

Headings

Use # symbols for headings. Use ## (H2) as your top-level heading inside notes since H1 is reserved for the note title.

## Section Title
### Subsection
#### Sub-subsection

Text Formatting

Syntax	Result
`bold`	bold
`italic`	italic
`*bold & italic*`	bold & italic
`inline code`	`inline code`
`~~strikethrough~~`	~~strikethrough~~
`==highlight==`	==highlight==

Links

Standard Markdown links:

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")

Autolinks — just paste a URL and it becomes clickable:

https://example.com

Images

Standard Markdown images:

![Alt text](https://example.com/image.jpg)
![Alt text](https://example.com/image.jpg "Optional title")

For local images, place files in public/images/notes/ and reference them:

![Description](/images/notes/my-photo.jpg)

Or use the Obsidian-style embed (see below).

Lists

Unordered list:

Item one
Item two
- Nested item
  - Deeply nested

Ordered list:

First step
Second step
Third step

Task list:

Completed task
Pending task
Another pending task

Blockquotes

This is a blockquote. It can span multiple lines.

And include multiple paragraphs.

Nested blockquotes:

First level

Second level

Third level

Horizontal Rules

Use ---, ***, or ___ on a line by itself to create a divider.

Code Blocks

Wrap code in triple backticks with an optional language for syntax highlighting:

function greet(name) {
  return `Hello, ${name}!`;
}

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

.highlight {
  background-color: #fef08a;
  padding: 0.2em 0.4em;
  border-radius: 4px;
}

Inline code uses single backticks: const x = 42;

Tables

| Left | Center | Right |
|:-----|:------:|------:|
| A    |   B    |     C |
| D    |   E    |     F |

Renders as:

Left	Center	Right
A	B	C
D	E	F

Footnotes

Add footnotes with [^label] and define them anywhere in the note:

This claim needs a source[^1].

[^1]: Source: Author, "Title", 2025.

This claim needs a source¹.

Obsidian Wikilinks

Wikilinks connect notes using [[double brackets]]. They create bidirectional links that show up in backlinks and the graph view.

Basic Wikilink

[[writing-guide]]

Links to a note by its slug (filename without .md).

Wikilink with Custom Text

[[writing-guide|Read the full guide]]

Use | to separate the target slug from the display text: Read the full guide

Link to a Specific Heading

[[writing-guide#Obsidian Callouts]]

Appending #heading links directly to a section: writing-guide > Obsidian Callouts

Linking by Alias

If a note has aliases: [syntax-guide] in its frontmatter, you can link to it using that alias:

[[syntax-guide]]

This resolves to the same note.

Transclusion (Embedding Notes)

Embed another note’s content inside the current note using ![[note-slug]]:

![[writing-guide]]

Embed a specific section:

![[writing-guide#Frontmatter]]

This pulls the content inline — great for reusing shared sections across notes.

Obsidian Callouts

Callouts are styled boxes that draw attention. Start a blockquote with > [!TYPE]:

Available Types

General information or supplementary detail.

[!TIP] Helpful Tip Callouts support custom titles — just add text after the type.

Important caution or something to watch out for.

Critical warning — something that can cause data loss or serious issues.

Positive outcome or completed action.

A question to consider or discuss.

[!EXAMPLE] Custom Title Here You can combine any callout type with a custom title.

Additional informational context.

Use this for attributed quotations or cited material.

Foldable Callouts

Add + or - after the type to make callouts collapsible:

[!NOTE]+ Expanded by default This callout starts open. Click the title to collapse it.

[!TIP]- Collapsed by default This callout starts closed. Click to expand. Great for long optional sections or spoilers.

Callout Syntax Summary

> [!TYPE]
> Content here.

> [!TYPE] Custom Title
> Content here.

> [!TYPE]+ Expanded by default
> Foldable, starts open.

> [!TYPE]- Collapsed by default
> Foldable, starts closed.

Highlights

Use ==double equals== to highlight text:

This is a ==key concept== you should remember.

This is a key concept you should remember. Highlights are great for important terms, definitions, or key takeaways.

Image Embeds (Obsidian Style)

Embed images stored in public/images/notes/ with Obsidian syntax:

![[my-photo.jpg]]
![[my-photo.jpg|Alt text description]]

The second form adds alt text after the | for accessibility.

Comments

Use %% to add comments that are invisible in the published output:

%%This is a hidden comment — only visible in the source.%%

Useful for leaving notes-to-self, TODOs, or editorial remarks while writing.

Quick Reference

Feature	Syntax
Bold	`text`
Italic	`text`
Highlight	`==text==`
Strikethrough	`~~text~~`
Inline code	`code`
Wikilink	`[[note-slug]]`
Wikilink (alias)	`[[slug\|display text]]`
Embed note	`![[note-slug]]`
Embed section	`![[note-slug#Heading]]`
Embed image	`![[image.jpg\|alt text]]`
Callout	`> [!TYPE] Title`
Foldable (open)	`> [!TYPE]+ Title`
Foldable (closed)	`> [!TYPE]- Title`
Comment	`%%hidden text%%`
Footnote	`[^label]`
Task	`- [ ] task` / `- [x] done`

Source: Author, “Title”, 2025. ↩