Add deployment guide and fix stale README theme listing
- Create guide.md: step-by-step deployment guide in ProjectPublic markup format, written for non-technical users - Add guide-format.txt: markup syntax reference - Fix README.md: remove references to deleted templates/ and parts/ directories in theme tree listing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
141
guide-format.txt
Normal file
141
guide-format.txt
Normal file
@@ -0,0 +1,141 @@
|
||||
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
|
||||
Reference in New Issue
Block a user