# Dylaris Site Manual

This guide is the source for the Manual page at `/manual.html`. The page reads this
Markdown file and renders it with marked.js. It also builds the side navigation
from the second- and third-level headings below.

So, if you update this file, the Manual page updates too.

## Quick Start

### What This Site Has

- `posts.html` lists blog posts.
- `toolbox.html` lists software, scripts, and config files you can download.
- `manual.html` is this guide.
- `assets/` holds shared styles, scripts, images, and third-party files.
- `tools/publish.py` creates new post and Toolbox pages for you.

The site is built with plain HTML, CSS, and JavaScript. There is no front-end build
step and nothing loads from a CDN at runtime.

### Publish Something in Five Steps

1. Prepare the Markdown file or download file.
2. Write a small JSON file that describes it.
3. Run the publish script with `--dry-run` to check the paths and fields.
4. Run the script again without `--dry-run` to create the pages.
5. Use `--deploy` when you want to commit and push the result.

```bash
python tools/publish.py item.json --dry-run
python tools/publish.py item.json
python tools/publish.py item.json --deploy
```

### Preview the Site Locally

The browser cannot load Markdown and JSON from a `file://` URL. Start a small local
web server instead:

```bash
python -m http.server 8000
```

Then open `http://localhost:8000/`.

### Publish Commands

| Command | What it does |
| --- | --- |
| `python tools/publish.py item.json` | Creates the page, copies files, and updates the list. |
| `python tools/publish.py item.json --dry-run` | Checks the JSON and source files without writing anything. |
| `python tools/publish.py item.json --overwrite` | Replaces an existing item with the same slug. |
| `python tools/publish.py item.json --deploy` | Creates the item, commits the generated files, and runs `git push`. |

`--deploy` only stages the new page folder and the list it updates. It leaves other
staged files alone.

## Site Layout

### Folder Structure

```text
.
├── index.html
├── posts.html
├── toolbox.html
├── manual.html
├── about.html
├── 404.html
├── assets/
│   ├── css/site.css
│   ├── js/
│   ├── images/
│   └── thirdparty/
├── posts/
│   ├── index.json
│   └── <slug>/
│       ├── index.html
│       ├── content.md
│       └── images/
├── toolbox/
│   ├── index.json
│   └── <slug>/
│       ├── index.html
│       └── files/
└── tools/
    ├── publish.py
    └── templates/
        ├── post.html
        └── tool.html
```

### What Each File Does

| File | Job |
| --- | --- |
| `posts/index.json` | Holds post cards, filter data, and post details. |
| `posts/<slug>/content.md` | Holds the post body. |
| `toolbox/index.json` | Holds Toolbox cards, details, and download data. |
| `toolbox/<slug>/files/` | Holds the actual download files. |
| `assets/css/site.css` | Holds the Firewatch theme and responsive layout. |
| `assets/js/post.js` | Renders post Markdown, the page outline, and copy buttons. |
| `assets/js/posts.js` | Handles the post list, search, and categories. |
| `assets/js/tool-detail.js` | Renders Toolbox details and download cards. |
| `assets/js/toolbox.js` | Handles the Toolbox list, search, and categories. |
| `assets/js/manual.js` | Renders this manual and creates its side navigation. |

## Publish a Post

### Post Input Example

```json
{
  "type": "post",
  "slug": "my-new-post",
  "title": "My New Post",
  "description": "A short description of the post.",
  "content_file": "./article.md",
  "date": "2026-11-06",
  "updated": "2026-11-06",
  "category": "systems",
  "tags": ["Linux", "C"],
  "readingTime": 6,
  "draft": false
}
```

`content_file` can be relative to the JSON file. The script creates:

```text
posts/my-new-post/index.html
posts/my-new-post/content.md
```

It also adds the post to `posts/index.json`.

### Post Fields

| Field | Required? | If you leave it out or use an empty value | What it affects |
| --- | --- | --- | --- |
| `type` | Yes | The script stops with an error. | Must be `post`. |
| `slug` | Yes | The script stops with an error. | Sets the URL and folder name. Use lowercase letters, numbers, and single hyphens. |
| `title` | Yes | The script stops with an error. | Shows on cards, the post page, and the browser tab. |
| `description` | No | No summary is shown. | Used by cards, search, and the page description. |
| `content_file` | Yes | The script stops with an error. | Path to the source Markdown file. |
| `date` | No | No date is shown, and the post sorts after dated posts. | Used on cards, the post page, and sorting. Use `YYYY-MM-DD`. |
| `updated` | No | No update date is shown. | Shown on the post page. It is hidden when it matches `date`. |
| `category` | No | No category or filter option is added. | Converted to lowercase and used for sorting. |
| `tags` | No | No tags are shown or searched. | Must be a list of strings. Tags also work as search terms. |
| `readingTime` | No | No reading time is shown. | Shows as text such as `6 min read`. |
| `draft` | No | Defaults to `false`. | When `true`, the post is hidden from the home page and post list. The URL still works. |

### Writing the Markdown

The page already shows the post title, so start the body with a second-level
heading:

```markdown
## First section

Text with **bold**, *italic*, and `inline code`.

### Subsection

- First item
- Second item
```

### Post Images

Put images that belong to one post in `posts/<slug>/images/`. Use a relative path
in the Markdown:

```markdown
![Diagram](./images/diagram.png)
```

The image description becomes the alt text. Compress large images before adding
them. WebP or an optimized PNG is a good choice.

## Publish a Toolbox Item

### Software or Script Example

```json
{
  "type": "tool",
  "slug": "my-tool",
  "name": "My Tool",
  "description": "One short sentence explaining what this tool does.",
  "license": "MIT",
  "copyright": "Copyright (c) The author",
  "website": "https://example.com/my-tool",
  "category": "software",
  "tags": ["CLI", "Python"],
  "added": "2026-11-06",
  "updated": "2026-11-06",
  "downloads": [
    {
      "version": "1.0.0",
      "label": "Windows x86_64",
      "source": "./my-tool-windows-x86_64.zip",
      "format": "ZIP",
      "platform": "Windows",
      "architecture": "x86_64",
      "notes": "Extract and run my-tool.exe."
    }
  ]
}
```

### Config File Example

Config files use `"type": "tool"` too. Pick a useful lowercase category such as
`dotfile` or `config`.

```json
{
  "type": "tool",
  "slug": "myvimrc",
  "name": "myvimrc",
  "description": "My Vim configuration without plugins.",
  "license": "MIT",
  "copyright": "Copyright (c) dylaris",
  "category": "dotfile",
  "tags": ["vim", "editor"],
  "downloads": [
    {
      "label": "Vim config",
      "source": "./.vimrc",
      "format": "TXT",
      "filename": ".vimrc",
      "notes": "Download and save it as ~/.vimrc in your home directory."
    }
  ]
}
```

### One Item, Many Builds

Keep one slug and one Toolbox card for the same software. Put every platform,
architecture, or file format in the same `downloads` list:

```json
"downloads": [
  {
    "version": "1.0.0",
    "label": "Windows x86_64",
    "source": "./tool-windows-x86_64.zip",
    "platform": "Windows",
    "architecture": "x86_64"
  },
  {
    "version": "1.0.0",
    "label": "Linux ARM64",
    "source": "./tool-linux-arm64.tar.gz",
    "platform": "Linux",
    "architecture": "ARM64"
  }
]
```

The Toolbox card does not show a version. The version appears only on its download
cards. Different builds can even use different versions.

### Toolbox Top-Level Fields

| Field | Required? | If you leave it out or use an empty value | What it affects |
| --- | --- | --- | --- |
| `type` | Yes | The script stops with an error. | Must be `tool`. |
| `slug` | Yes | The script stops with an error. | Sets the Toolbox URL, folder name, and unique ID. |
| `name` | Yes | The script stops with an error. | Shows on the card and the Toolbox detail page. |
| `description` | No | No summary is shown. | Used by cards, search, and the page description. |
| `license` | No | The License row is hidden. | Shown only on the detail page. |
| `copyright` | No | The Copyright row is hidden. | Shown only on the detail page. |
| `website` | No | The Official website button is hidden. | Links to the project homepage or docs. |
| `category` | No | No category or filter option is added. | Converted to lowercase and used for filtering. |
| `tags` | No | No tags are shown or searched. | Must be a list of strings. Tags also work as search terms. |
| `added` | No | Nothing is stored. | Helps sort items when `updated` is missing. It is not shown on the page. |
| `updated` | No | No update date is shown. | Shown on the detail page and used for sorting. |
| `downloads` | Yes | The script stops with an error. | Needs at least one item with a valid `source`. |

### Download Fields

| Field | Required? | If you leave it out or use an empty value | What it affects |
| --- | --- | --- | --- |
| `source` | Yes | The script stops with an error. | The local file path. Relative paths use the JSON file's folder as the starting point. |
| `label` | No | Uses the source filename. An explicit empty value hides the title. | The title on the download card. |
| `version` | No | No version badge is shown. | Appears only in the Downloads area. |
| `file` | No | Uses the source filename. | The stored filename inside `files/`. Only the basename is kept. |
| `filename` | No | Usually follows `file`. A hidden source file uses its original name. | The filename suggested to the browser when someone downloads it. It does not change the stored file. |
| `format` | No | Guessed from the extension and shown in uppercase. | Used on the format badge and download button. |
| `platform` | No | The platform badge is hidden. | Shows which system the file is for and helps search. |
| `architecture` | No | The architecture badge is hidden. | Shows which CPU type the file is for and helps search. |
| `notes` | No | The note paragraph is hidden. | Use this for extract, install, save, or rename steps. |

### Stored Name vs. Download Name

Three filename fields do different jobs:

| Field | Example | What it means |
| --- | --- | --- |
| `source` | `./.vimrc` | Where the file lives on your computer. |
| `file` | `vimrc` | The filename stored inside `files/`. |
| `filename` | `.vimrc` | The name suggested to the browser for downloads. |
| `label` | `Vim config` | The title shown on the page. |

Hidden files lose their leading dot when stored. For example, `.vimrc` is stored as
`vimrc` by default. Some browsers also remove the leading dot from a download name.
If that matters, mention the real filename in `notes`.

### Values the Script Adds

You do not need to fill in these values yourself:

| Field | What the script does |
| --- | --- |
| Final `file` value | Turns it into `files/<stored filename>`. |
| `size` | Reads the real file size, such as `1.71 MB`. |
| `sha256` | Reads the real file and creates a SHA-256 checksum. |
| `format` | Guesses the format when you leave it out. |

`size` and `sha256` always appear because they come from the actual file, not from
optional text fields.

## Empty Fields and Defaults

### Empty Fields on the Site

An empty string, empty list, `null`, or missing optional field does not create empty
space or placeholder text on the site.

- Cards skip an empty summary, category, or tag list.
- Detail pages skip an empty License, Copyright, Website, version, platform, or
  architecture value.
- Posts skip empty dates, update dates, categories, tags, or reading times.
- Download cards skip an empty label, version, platform, architecture, or note.

In most cases the publish script also removes the empty value from the JSON list
instead of writing `undefined` or fake default text.

### Things the Script Guesses or Defaults

- A bad `slug` stops the script.
- `category` is converted to lowercase.
- `format` is guessed from the file extension when omitted.
- `label` uses the source filename when omitted.
- `size`, `sha256`, and the final `file` path are always created from the file.
- `draft` defaults to `false`.

### Category Rules

- Use lowercase categories, such as `software`, `dotfile`, `embedded`, or `web`.
- The first item in a category filter says `ALL`.
- Category choices come from the JSON lists. You do not need to edit the page
  separately.

## Templates and Manual Edits

### Detail Page Templates

The publish script uses these files:

```text
tools/templates/post.html
tools/templates/tool.html
```

Changing a template only affects pages created later. To rebuild an existing page,
publish it again with `--overwrite`, or edit its `index.html` by hand.

### Add a Toolbox Item Without the Script

1. Create `toolbox/<slug>/`.
2. Copy the detail page template and replace `{{SLUG}}`, `{{NAME}}`, and
   `{{DESCRIPTION}}`.
3. Add the download file to `toolbox/<slug>/files/`.
4. Add the item to `toolbox/index.json`.
5. Fill in `file`, `size`, and `sha256` yourself.

Use lowercase categories when editing the JSON by hand too.

### Add a Regular Page

1. Copy `about.html` as a starting point.
2. Change the `<title>`, description, and `<main>` content.
3. Add the page to the navigation and set `aria-current="page"` on the current page.
4. Put page-specific code in its own file under `assets/js/`.

### Update This Manual

Edit `BLOG_GUIDE.md`. The `/manual.html` page reads this file whenever it loads.

- Second-level headings become the main modules in the side navigation.
- Third-level headings become smaller links inside each module.
- Code blocks get copy buttons automatically.
- There is no separate web copy to update.

## Theme and Layout

### Firewatch Theme

The site uses the colors from `vim-two-firewatch`. They live at the top of
`assets/css/site.css`:

```css
:root[data-theme="light"] {
  --page-bg: #faf8f5;
  --text: #896724;
  --blue: #447ebb;
}

:root[data-theme="night"] {
  --page-bg: #282c34;
  --text: #abb2bf;
  --blue: #56b6c2;
}
```

Light is the default theme. Your choice is saved in
`localStorage.firewatch-theme`.

To go back to the default light theme, run this in the browser console:

```js
localStorage.removeItem('firewatch-theme');
```

### Fonts

The site uses system monospace fonts:

```css
Consolas, "Cascadia Mono", Menlo, "Liberation Mono", monospace
```

Windows uses Consolas first. Other systems use the next available fixed-width font.

### Header and Footer

- The header stays at the top while you scroll. It is about 60px tall.
- The footer stays at the bottom when a page is short.
- If the page is taller than the screen, the footer follows the content.
- Every post and Toolbox detail page needs the `.site-footer` block.

## Markdown and Media

### Supported Markdown

marked 15.0.12 supports GitHub Flavored Markdown:

- Headings, bold, italic, strikethrough, and lists.
- Normal links, automatic links, and images.
- Inline code and fenced code blocks.
- Quotes, tables, and task lists.

### Code Blocks

````markdown
```c
int main(void) {
    return 0;
}
```
````

Post and Manual code blocks both get a copy button.

### External Links

Links that start with `http` or `https` open in a new tab and use
`rel="noopener noreferrer"`.

### Markdown Safety

marked allows inline HTML by default. Only publish Markdown that you wrote or trust.
Do not paste a stranger's Markdown into the site without checking it.

## Optional Features

### Code Highlighting

1. Download the browser build and styles for highlight.js.
2. Put them in `assets/thirdparty/`.
3. Load them only on pages that need syntax highlighting.
4. After marked renders the page, call `hljs.highlightElement(block)`.

The copy button code does not need to change.

### Math

1. Download KaTeX and its fonts to `assets/thirdparty/katex/`.
2. Load it only on pages that use formulas.
3. After marked renders the page, call `renderMathInElement(content)`.

Do not load KaTeX on normal posts. It adds font files the page may never use.

### RSS

GitHub Pages does not create RSS for you. A simple option is to maintain `feed.xml`
by hand and add an `<item>` when you publish a post:

```xml
<item>
  <title>Article title</title>
  <link>https://dylaris.github.io/posts/my-new-post/</link>
  <guid>https://dylaris.github.io/posts/my-new-post/</guid>
  <pubDate>Thu, 06 Nov 2026 00:00:00 +0800</pubDate>
  <description>Article summary</description>
</item>
```

Then add this to the page `<head>`:

```html
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
```

### Social Cards and Open Graph

Put social data directly in each detail page:

```html
<meta property="og:title" content="Article title" />
<meta property="og:description" content="Article summary" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://dylaris.github.io/posts/my-new-post/" />
<meta property="og:image" content="https://dylaris.github.io/assets/images/cover.png" />
```

Most social sites do not run page JavaScript. They need these values in the HTML.

### Comments

The site has no backend. A service such as Giscus can use GitHub Discussions for
comments. Add the script it gives you after a detail page's content.

This sends requests to a third party. If you want a fully self-contained site, skip
comments.

### Reading Progress

Add an empty progress element to a post page and listen to page scrolling:

```js
const documentHeight = document.documentElement.scrollHeight - window.innerHeight;
const progress = window.scrollY / documentHeight;
```

Turn `progress` into a width. You do not need a library for this.

### Full-Text Search

The current search covers titles, summaries, categories, tags, platforms,
architectures, and formats. For full-text search, create a
`posts/search-index.json` with plain-text snippets, then read it from `posts.js`.

## Troubleshooting

### Basic Checks

1. Open the browser Console and look for red errors.
2. In Network, check that HTML, JSON, Markdown, images, and downloads return 200.
3. Open the detail URL directly and confirm that the page exists.
4. Check that the JSON is valid. A trailing comma will break it.
5. Check that the folder name, `data-post-slug` or `data-tool-slug`, and JSON
   `slug` all match.
6. Hard-refresh the page to clear old CSS and JavaScript.
7. Add one feature at a time and test before moving on.

### The Page Is Missing Content

- Posts: check `posts/index.json` and `content.md`.
- Toolbox: check `toolbox/index.json` and `files/`.
- Manual: check `BLOG_GUIDE.md`.
- Check the request paths, spelling, and uppercase/lowercase letters.

### A Download Gives a 404

- Check that the `file` path exists inside `toolbox/<slug>/files/`.
- Check uppercase and lowercase letters in the filename.
- Remember that hidden files lose their leading dot when stored.

### Old Pages Did Not Change After I Edited a Template

Templates only affect future pages. Publish the old item again with `--overwrite`, or
edit the existing `index.html` directly.

## Rules of Thumb

- If HTML can do it, start there before writing JavaScript.
- Put page-only scripts in their own file.
- Put third-party code in `assets/thirdparty/` and avoid runtime CDNs.
- Write down the version, source, license, and checksum when updating a third-party
  library.
- Use lowercase categories.
- Show versions only on download items.
- Do not add fake placeholder text for empty fields.
- Avoid adding a build tool until the site is genuinely hard to maintain without one.
