2.1-markdown-files

Overview

An archive is a structured collection of stored records, documents, or files preserved for long-term reference, historical documentation, or systematic retrieval.

What is a Markdown File

A Markdown file is a plain text file written using the Markdown syntax, a lightweight markup language created by John Gruber in 2004. It uses simple symbols and characters to define the formatting of a document without requiring a dedicated word processor or complex software.

Markdown files carry the .md or .markdown file extension.

Core Characteristics

• The content is written in plain text, meaning it can be opened and edited with any basic text editor
• Formatting is expressed through symbols rather than visual controls, for example a # symbol before a line defines a heading
• The file is human-readable in its raw form, even before it is rendered
• It can be converted into HTML, PDF, or other formats by compatible tools and platforms

Common Uses

• Documentation for software projects
• Notes and knowledge base entries
• README files in code repositories
• Static website content
• Personal or professional writing workflows

Basic Syntax Examples

Markdown is widely adopted in archiving and documentation workflows because of its simplicity, portability, and compatibility with version control systems.

2.1 Archives Overview

The archives pipeline compiles any local folder with markdowns archive into a static website at build time. Folder hierarchies are ignored — frontmatter metadata acts as the “public routing table,” deciding what is published and where.

Core Philosophy: The folder tree is private filing. The frontmatter is the public address.

Frontmatter in Markdown

Frontmatter is a block of structured metadata written at the very top of a Markdown file, enclosed between two sets of triple dashes (---). It is not rendered as visible content — instead, it provides machine-readable information about the document to whatever tool or platform is processing the file.

Structure

---
title: My Note
publish: true
permalink: /my-note/
---

# Actual document content starts here

The block must appear at the absolute beginning of the file. Everything between the opening and closing --- delimiters is parsed as YAML key-value pairs.

What It Contains

Frontmatter holds descriptive properties about the document (like metadata) rather than the document’s content itself. Common examples include:

• The document title
• Creation or modification dates
• Tags or categories
• Author information
• Custom flags used by build tools

Its Role in the Archives Pipeline

In the context of this system, frontmatter functions as the public routing contract for every note. The pipeline reads it at build time to make the following decisions:

A note without publish: true in its frontmatter is ignored entirely, regardless of where it sits in the folder hierarchy.

Key Point

The folder a file lives in has no effect on its public URL or visibility. The frontmatter alone determines both. This is what the documentation means by the phrase: the folder tree is private filing, the frontmatter is the public address.

1. Integration Setup

To boot the vault processor, specify its local folder location in your astro.config.mjs:

import { defineConfig } from "astro/config";
import standard from "@stnd/core";

export default defineConfig({
  integrations: [
    standard({
      vault: "./vault", // Path to your Obsidian vault relative to application root
    }),
  ],
});

During the build phase, @stnd/core configures the Vite file watcher to hot-reload vault files and generates index files automatically.

2. Frontmatter Contract

Every note intended for the web must carry publish: true in its frontmatter. Notes without this flag are private by default and will be excluded during build compilation.

---
title: My Custom Note
publish: true
visibility: public       # public (default) | unlisted | private
permalink: /my-note/    # Explicit canonical URL
theme: chronicle        # Note-specific visual layout
---

Metadata Fields Schema

3. URL Resolution Mechanics

Standard generates URLs using a strict priority chain:

1. Explicit permalink: If permalink: /hello/ is defined, the page is compiled exactly as /hello/index.html.
2. Explicit title: If no permalink exists, the frontmatter title is slugified (e.g., title: My Note $\to$ /my-note).
3. File Basename: As a fallback, the note’s filesystem name is slugified (e.g., About_Me.md $\to$ /about-me).

4. Wikilink Parsing

@stnd/press parses Obsidian’s double-bracket wikilinks [target](target.md) at compile time:

• Slug Matching: Resolves target references against compiled slugs (e.g., [setup](setup.md) maps to /guides/setup).
• Filename / Title Fallbacks: Resolves references against filenames or H1 titles. For instance, [About - Now](About - Now.md) will successfully map to a page even if the note’s explicit permalink is set to /now/.
• Display Text: Custom labels are supported using the pipe character (e.g., [See Configuration Guide](setup.md)).
• Broken Links: If a target note does not exist in the compiled pool, the link renders safely as <span class="broken-link">target</span> to prevent layout breaks.

5. Asset Management & Flat Resolution

Markdown image embeds (![attachment.png](attachment.png.md)) are automatically parsed and copied:

• Flat Namespace Matching: Following Obsidian guidelines, assets are resolved flat across the entire vault. The parser searches directories, and the first file matching the name wins.
• Copying on Build: Compiled assets are processed, renamed to match clean slugs, and copied directly to the output directory at public/assets/vault/.
• CDN Rewriting: If hosted on the edge, the image loader rewrites relative paths to optimized Cloudflare CDN paths dynamically.

6. Build Lifecycle & Hygiene

To prevent orphaned or renamed files from lingering in production, standard deployment scripts should always purge previous builds completely:

"build": "rm -rf dist && astro build"

Without clean builds, stale html files from deleted, unmapped, or renamed notes would remain active on your web server.

2.2-archives-standard