Content Organization

Hanamark mirrors your source directory structure in the output.

Directory Mapping

source_md/                    output_html/
├── about.md            ->    ├── about.html
├── projects.md         ->    ├── projects.html
└── blog/                     └── blog/
    ├── _index.md       ->        ├── index.html (list page)
    ├── post-1.md       ->        ├── post-1.html
    └── post-2.md       ->        └── post-2.html

Single Pages

Any .md file (except _index.md) becomes a single HTML page:

---
created_on: 2024-01-15
tags: ["about", "personal"]
---

# About Me

This is my about page content...

Output: about.html

List Pages (Sections)

Directories with a _index.md file become sections with automatic list pages.

Important: If you want a list page, it is mandatory to have _index.md in that folder.

blog/
├── _index.md           # Section configuration
├── post-1.md           # Blog post
├── post-2.md           # Blog post
└── nested/             # Nested section
    ├── _index.md
    └── deep-post.md

The _index.md file configures the section:

---
rss: true
template: "blog/custom_list_template.html"
---

Output: blog/index.html with links to all posts in the section.

Nested Sections

You can nest sections as deep as you need:

docs/
├── _index.md
├── intro.md
└── guides/
    ├── _index.md
    ├── beginner.md
    └── advanced.md

Each section with _index.md gets its own list page.

Companion Files (Link Targets, Not Posts)

Sometimes you want a .md file’s own subfolder to hold files that are only meant to be linked to from that file — not shown as standalone posts. Name the folder the same as the file (minus .md) and Hanamark treats every .md inside as a companion file:

blog/
├── paper_reading.md            # normal post
└── paper_reading/              # folder name matches paper_reading.md
    └── mpr.md                  # companion file

Companion files are still rendered to HTML (so links to them work), but they are:

excluded from the parent section’s list page
excluded from tag pages, even if they set tags in frontmatter

Output: paper_reading.html and paper_reading/mpr.html, but blog/index.html lists only paper_reading.html.

Linking Between `.md` Files

Write links to other posts using their .md source path, and Hanamark rewrites the destination to .html at render time:

[map reduce](./paper_reading/mpr.md)

Renders as:

<a href="./paper_reading/mpr.html">map reduce</a>

External links (https://...), mailto: links, and anchors/query strings are left untouched.