websitebox/guide-format.txt

 ProjectPublic Markup Syntax — Complete Reference

  Document Structure

  Every document has two parts: frontmatter (metadata) and steps (content).

  Frontmatter

  Must be the first thing in the document, delimited by ---:

  ---
  title: Your Project Title Here
  summary: A brief 1-2 sentence description of what this guide covers
  tags: Docker, Linux, Networking
  difficulty: beginner
  time: 45 minutes
  prerequisites: Basic Linux knowledge, SSH access
  video: https://youtube.com/watch?v=example
  ---

  Required fields:
  - title — project title (max 120 chars)
  - summary — short description (max 280 chars)
  - tags — comma-separated list (at least 1)
  - difficulty — one of: beginner, intermediate, advanced

  Optional fields:
  - time — estimated time (e.g., "45 minutes", "2 hours")
  - prerequisites — comma-separated list
  - video — URL to an accompanying video

  Steps

  Each step starts with [step: Step Title] on its own line:

  [step: Install Docker]

  Content goes here...

  [step: Configure the Container]

  More content...

  At least one step is required. Steps are numbered automatically (1, 2, 3...).

  Element Types (within steps)

  1. Text (Markdown)

  Plain text between block tags is treated as Markdown. Supports standard Markdown:

  This is a paragraph with **bold**, *italic*, and `inline code`.

  - Bullet list item
  - Another item

  1. Numbered list
  2. Second item

  [Links work like this](https://example.com)

  > Blockquotes work too

  2. Code Block

  [code:bash | install.sh]
  sudo apt update
  sudo apt install docker.io
  systemctl enable --now docker
  [/code]

  - Syntax: [code:language | filename]...[/code]
  - language — syntax highlighting language (e.g., bash, python, yaml, json, javascript, dockerfile)
  - | filename — optional, displayed as a tab/label above the code
  - Both are optional: [code]...[/code] works with no language or filename

  3. Terminal Output

  [terminal]
  $ docker ps
  CONTAINER ID   IMAGE     STATUS
  a1b2c3d4e5f6   nginx     Up 2 hours
  [/terminal]

  - Syntax: [terminal]...[/terminal]
  - Used for showing expected command output, logs, or interactive terminal sessions
  - Rendered with a terminal-style dark background

  4. Callout

  [callout:info]
  Docker must be running before you proceed to the next step.
  [/callout]

  [callout:warning]
  This will delete all existing containers. Back up your data first.
  [/callout]

  [callout:danger]
  Never run this command on a production server without testing first.
  [/callout]

  [callout:tip]
  You can add this to your .bashrc to make it permanent.
  [/callout]

  - Syntax: [callout:variant]...[/callout]
  - Variants: info, warning, danger, tip
  - Content inside supports Markdown

  5. Image

  [image: https://example.com/screenshot.png | Screenshot of the dashboard]

  - Syntax: [image: url | caption]
  - url — image source URL (required)
  - | caption — optional, used as both alt text and caption

  6. Video

  [video: https://example.com/demo.mp4]

  - Syntax: [video: url]
  - Accepts direct video URLs (MP4, WebM)

  7. URL Embed

  [url: https://github.com/example/repo]

  - Syntax: [url: href]
  - Renders as a linkcard/embed

--
  Notes for Guide Authors

  - Every block tag ([code], [terminal], [callout]) must have a matching closing tag ([/code],
[/terminal], [/callout])
  - [image], [video], and [url] are self-closing (no closing tag needed)
  - Standard Markdown links [text](url) work in text sections and are not confused with block tags
  - Frontmatter fields use key: value syntax (one per line, no nesting)
  - The parser round-trips: markup → JSON → markup without data loss