____ _ ____ ____ ____ | _ \(_) ___ ___/ ___/ ___| / ___| | |_) | |/ __/ _ \___ \___ \| | _ | __/| | (_| (_) |__) |__) | |_| | |_| |_|\___\___/____/____/ \____|

File Mapping

One of PicoSSG's core principles is its predictable 1:1 file mapping from input (content) to output files. The output files are those served by a web server, your website structure.

This page explains how PicoSSG maps source files to output files.

Basic Principle

PicoSSG follows a straightforward rule: each source file in your content directory maps directly to an output file in your output directory, with the same relative path.

The only changes that happen are:

  1. Files are processed based on their extension(s) (.njk, .md)
  2. Processed extensions are removed from filenames when outputting
  3. If no extension remains after processing, .html is automatically added
  4. Files and directories prefixed with _ are excluded from the output

File Processing

PicoSSG processes files based on their extensions, from right to left. It removes the extensions it processes, and if no extension remains, it adds .html:

Source File Output File Processing Steps
about.html.md about.html Process as Markdown
page.html.njk page.html Process as Nunjucks
style.css.njk style.css Process as Nunjucks
post.html.md.njk post.html Process as Nunjucks, then as Markdown
index.md index.html Process as Markdown, add .html extension
about.md about.html Process as Markdown, add .html extension
style.css style.css No processing, copy as-is
index.html index.html No processing, copy as-is

Important: You can now use either about.html.md or just about.md - both will result in about.html. If you use just about.md, PicoSSG will automatically add the .html extension since no extension remains after processing. If you use both one will override the other.

Directory Processing

PicoSSG preserves your directory structure exactly:

content/                   output/
├── index.html.md          ├── index.html
├── _config.js             │
├── _base.njk              │
├── about/                 ├── about/
│   └── index.md           │   └── index.html
├── blog/                  ├── blog/
│   └── post1.md           │   └── post1.html
├── _components/           │
│   └── base.njk           │
└── css/                   └── css/
    └── style.css              └── style.css

Markdown files can be named either .md or .html.md - both will generate HTML files. The files and directories starting with _ are excluded from the output.

_* Files/Directories

Files and directories starting with an underscore are excluded from the output. This is perfect for:

Example:

content/                   output/
├── _base.njk              (not copied/processed)
├── _includes/             (not copied/processed)
├── index.md               ├── index.html
└── about.html.md          └── about.html

Processing Flow

When PicoSSG builds your site, it:

  1. Calls preCreateProcessors(config) function if present in _config.js
  2. Scans the content directory recursively
  3. Looks at each file, stores all that do not start with _ and it determines if processing is needed, or just copying, these info are stored in the files map.
  4. Runs the preprocess() function if present in _config.js
    • This function can modify the file content before processing
    • If _config.js is not present, it skips this step
  5. Extracts and remove front matter if present
    • Front matter is YAML metadata at the top of the file, provide the data to the template engine
    • It can include layout information, title, and any metadata
  6. From here on the following files are processed:
    • Markdown files (.md)
    • Nunjucks templates (.njk)
    • Combined files (like .njk.md)
    • all others are copied as-is (like .css, .js, etc.)
  7. Runs the postprocess() function if present in _config.js
    • This function can modify the file content after processing
    • If _config.js is not present, it skips this step
  8. Writes the processed files to the output directory (the copied one had been copied already)

The processing order for extensions is important: extensions are processed from right to left:

Filename Examples

Files Copied as-is

The files below use no special extensions and are copied as-is, no matter their extension, PicoSSG just moves them to the output directory:

index.html → index.html (copied as-is)
style.css → style.css (copied as-is)
favicon.ico → favicon.ico (copied as-is)
somefile.pdf → somefile.pdf (copied as-is)

Markdown Content

The files below are processed as Markdown, and the .md extension is removed in the output. If no extension remains after processing, .html is automatically added:

about.html.md → about.html (processed as Markdown)
about.md → about.html (processed as Markdown, `.html` extension added)
index.md → index.html (processed as Markdown, `.html` extension added)

Nunjucks Template

If the file ends with .njk, it is processed as a Nunjucks template, and the .njk extension is removed in the output. Notice that multiple extensions are processed from right to left, so file.html.md.njk is possible too:

contact.html.njk → contact.html (processed as Nunjucks)
post.html.md.njk → post.html (processed as Nunjucks, then Markdown)
style.css.njk → style.css (processed as Nunjucks, output as CSS)

Related Topics