From 4464774c7a3a66df7307815a00026e4bc8769ad4 Mon Sep 17 00:00:00 2001 From: ruohki Date: Sun, 1 Mar 2026 11:58:01 +0100 Subject: [PATCH] content: create demo vault with splash art and feature showcase pages 8 files: index.md with wiki-links, features overview, navigation guide, markdown showcase (all constructs), about page, changelog, and two guides (sysop handbook, writing content) in a subdirectory. Includes ANSI art splash.txt for the index page header. --- vault/about.md | 71 ++++++++++++++ vault/changelog.md | 64 ++++++++++++ vault/features.md | 77 +++++++++++++++ vault/guides/sysop-handbook.md | 79 +++++++++++++++ vault/guides/writing-content.md | 69 +++++++++++++ vault/index.md | 40 ++++++++ vault/markdown-showcase.md | 166 ++++++++++++++++++++++++++++++++ vault/navigation-guide.md | 67 +++++++++++++ vault/splash.txt | 8 ++ 9 files changed, 641 insertions(+) create mode 100644 vault/about.md create mode 100644 vault/changelog.md create mode 100644 vault/features.md create mode 100644 vault/guides/sysop-handbook.md create mode 100644 vault/guides/writing-content.md create mode 100644 vault/index.md create mode 100644 vault/markdown-showcase.md create mode 100644 vault/navigation-guide.md create mode 100644 vault/splash.txt diff --git a/vault/about.md b/vault/about.md new file mode 100644 index 0000000..a265940 --- /dev/null +++ b/vault/about.md @@ -0,0 +1,71 @@ +--- +description: About BBS-MD and its design philosophy +--- + +# About BBS-MD + +## What Is This? + +BBS-MD is a terminal-based markdown vault reader that channels the aesthetic of 1990s bulletin board systems. It turns a folder of markdown files into a navigable, interlinked information system — like a personal wiki you browse over SSH. + +## Design Philosophy + +### Terminal-Native + +BBS-MD is built for the terminal. No web browser, no Electron, no GUI toolkit. Just your terminal emulator, a monospace font, and 16 colors. It runs over SSH, in tmux, on a Raspberry Pi, on a VPS — anywhere you have a shell. + +### Vault as Filesystem + +Your content is just markdown files in a directory. No database, no proprietary format, no lock-in. Edit with vim, VS Code, or `echo >>`. BBS-MD watches for changes and refreshes live. + +### Retro Aesthetic + +The CGA 16-color palette isn't a limitation — it's a feature. Box-drawing characters for code blocks and tables. ANSI art on the landing page. Reverse-video status bar. Every design choice asks: *would a SysOp in 1994 approve?* + +### Safe by Default + +BBS-MD is designed to run as a login shell. That means: + +- A panic must never leave the terminal broken +- A disconnect must never corrupt state +- The user must always be able to exit +- The app must always restore the terminal + +These aren't nice-to-haves. When your app *is* the shell, safety is the foundation. + +## Tech Stack + +| Component | Technology | +|----------------|-------------------| +| Language | Rust (Edition 2024) | +| TUI Framework | ratatui 0.30 | +| Terminal | crossterm | +| Markdown | pulldown-cmark (GFM) | +| Highlighting | syntect | +| ANSI Art | ansi-to-tui | +| File Watching | notify 6.1 | +| Dir Traversal | walkdir 2.5 | + +## Architecture + +``` +bbs-md/ + src/ + main.rs Entry point, terminal init, event loop + app.rs App state, navigation, key handling + config.rs TOML config loading (bbs.toml) + vault.rs Document loading, wiki-link resolution + renderer.rs Markdown-to-styled-lines pipeline + highlighter.rs Syntax highlighting with CGA colors + splash.rs ANSI art splash screen loader + signals.rs Unix signal handlers (SIGHUP, SIGTERM) + terminal.rs Terminal init/restore, panic hook + vault/ + index.md Landing page (splash.txt prepended) + splash.txt ANSI art header (optional) + *.md Your content lives here +``` + +> BBS-MD is a single binary with no runtime dependencies. Compile it, drop it on a server, point it at a vault. + +Back to [[index|home]] or read the [[Changelog]]. diff --git a/vault/changelog.md b/vault/changelog.md new file mode 100644 index 0000000..7ac4a9b --- /dev/null +++ b/vault/changelog.md @@ -0,0 +1,64 @@ +--- +description: Version history and release notes +--- + +# Changelog + +All notable changes to BBS-MD are documented here. + +## v1.0.0 — 2026-03-01 + +The initial release. Four phases of development, ten plans executed. + +### Phase 1: Safety Foundation + +- Panic hook restores terminal state before unwinding +- SIGHUP and SIGTERM signal handlers for graceful shutdown +- Login shell detection (`argv[0]` dash prefix) +- TOML configuration via `bbs.toml` +- Double Ctrl+C quit confirmation (critical for login shell mode) + +### Phase 2: Vault Core and Rendering + +- Full GFM markdown rendering pipeline via pulldown-cmark +- Syntax-highlighted fenced code blocks with box-drawing borders +- Tables with aligned columns and full grid borders +- Scrolling with j/k, arrow keys, PgUp/PgDn +- Error screens for missing or unreadable documents +- Terminal resize re-rendering + +### Phase 3: Navigation and Links + +- Wiki-link resolution (`[[Page Name]]` to `page-name.md`) +- Standard markdown link following (`[text](path.md)`) +- Browser-style back/forward navigation history +- Modal link cycling with Tab to enter, Up/Down to navigate +- Draw-time REVERSED highlight on selected links +- Breadcrumb path display in status bar +- Broken wiki-link detection at render time (red strikethrough) + +### Phase 4: BBS Polish and Live Content + +- ANSI art splash screen on index.md via `splash.txt` +- File metadata in status bar (last modified date, file size) +- Virtual `[[Directory]]` page with tree view of all vault files +- Live filesystem watching with 300ms debounce auto-refresh +- Arrow key navigation (Left/Right for back/forward) +- Frontmatter description display in directory listing + +--- + +## Roadmap + +Future ideas (not yet planned): + +- Theming support (different color palettes) +- Search across vault documents +- Bookmarks and favorites +- Multi-vault support +- SSH server built-in (no external sshd needed) +- User authentication and access control + +--- + +Back to [[index|home]] or see [[About]]. diff --git a/vault/features.md b/vault/features.md new file mode 100644 index 0000000..07e4cf0 --- /dev/null +++ b/vault/features.md @@ -0,0 +1,77 @@ +--- +description: Full feature breakdown with examples +--- + +# Features + +BBS-MD is a terminal-based markdown vault reader built in Rust. Here's everything it can do. + +## Markdown Rendering + +BBS-MD renders a full subset of GitHub-Flavored Markdown with retro CGA-themed styling: + +- **Headers** (H1-H6) with distinct colors and decorators +- **Bold**, *italic*, and ~~strikethrough~~ text +- `Inline code` with syntax highlighting +- Fenced code blocks with language-aware highlighting +- Ordered and unordered lists with nesting +- Blockquotes with yellow pipe borders +- Tables with full box-drawing grid borders +- Horizontal rules +- Image placeholders + +### Code Block Example + +```rust +fn main() { + println!("Welcome to BBS-MD!"); + let vault = Vault::new("./vault"); + vault.browse(); +} +``` + +### Table Example + +| Feature | Status | Since | +|----------------|-----------|---------| +| Markdown | Complete | Phase 2 | +| Wiki-Links | Complete | Phase 3 | +| ANSI Splash | Complete | Phase 4 | +| Live Reload | Complete | Phase 4 | + +## Wiki-Link Navigation + +Connect your documents with `[[Wiki Links]]`. BBS-MD resolves them at render time: + +- `[[Page Name]]` — links to `page-name.md` (case-insensitive, hyphenated) +- `[[Directory]]` — special magic link to the vault directory listing +- Broken links are shown in ~~red strikethrough~~ so you know what needs fixing + +See the [[Navigation Guide]] for the full key binding reference. + +## ANSI Art Splash Screen + +Place a `splash.txt` file in your vault root containing ANSI escape codes. BBS-MD parses it with `ansi-to-tui` and displays it as a colorful header above your `index.md` content. If the file is missing, the index renders normally with no error. + +## Live Filesystem Watching + +Edit your markdown files in any editor. BBS-MD watches for changes and auto-refreshes the currently displayed page within about a second. Rapid saves are debounced — you won't see flickering. + +- Watches the parent directory of the current file +- Survives atomic saves (vim, neovim style) +- Non-fatal: if the watcher fails, the app still works without live reload + +## Directory Listing + +Navigate to `[[Directory]]` to see a tree view of every document in your vault. Directories appear in **yellow bold**, files as cyan bracketed links. Tab-cycle through entries and press Enter to open any document. + +## Safe Login Shell Mode + +BBS-MD can be set as a user's login shell for SSH access. In this mode: + +- `q` key is disabled (only double Ctrl+C exits) +- Panic hook restores the terminal before crashing +- Signal handlers (SIGHUP, SIGTERM) clean up gracefully +- The terminal is always left in a usable state + +Back to [[index|home]]. diff --git a/vault/guides/sysop-handbook.md b/vault/guides/sysop-handbook.md new file mode 100644 index 0000000..4301da7 --- /dev/null +++ b/vault/guides/sysop-handbook.md @@ -0,0 +1,79 @@ +--- +description: Running BBS-MD as a public SSH service +--- + +# SysOp Handbook + +So you want to run a BBS. Welcome to the club. + +## Setting Up SSH Access + +The classic BBS experience: users connect via SSH and land directly in BBS-MD. + +### 1. Create a BBS User + +```bash +# Create user with bbs-md as their login shell +sudo useradd -m -s /usr/local/bin/bbs-md bbsguest + +# Set up their vault +sudo mkdir -p /home/bbsguest/vault +sudo cp -r /path/to/your/vault/* /home/bbsguest/vault/ + +# Set a password (or use SSH keys) +sudo passwd bbsguest +``` + +### 2. Configure bbs.toml + +Place `bbs.toml` next to the binary or in the user's home directory: + +```toml +vault_path = "/home/bbsguest/vault" +theme = "default" +``` + +### 3. Test the Connection + +```bash +ssh bbsguest@your-server.com +``` + +The user lands directly on the index page. No shell prompt, no confusion. Just content. + +## Security Considerations + +- BBS-MD runs as a **login shell** — there is no escape to bash +- The `q` key is **disabled** in login shell mode +- Only double `Ctrl+C` can exit (returns to SSH disconnect) +- Path traversal is guarded — `../../etc/passwd` won't resolve +- Only `.md` files inside the vault are accessible + +## Content Management + +Your vault is just a directory of markdown files. You can: + +- Edit files over SFTP or SCP +- Use `rsync` to sync from a local copy +- Mount a Git repository and pull updates +- Write a cron job to generate content + +BBS-MD watches for changes. Your updates appear live. + +> The best BBS is the one that's always fresh. + +## Monitoring + +Watch the process with standard Unix tools: + +```bash +# Check if bbs-md is running for connected users +ps aux | grep bbs-md + +# Watch vault changes in real time +inotifywait -m /home/bbsguest/vault/ +``` + +--- + +Back to [[index|home]] or see the [[Features]]. diff --git a/vault/guides/writing-content.md b/vault/guides/writing-content.md new file mode 100644 index 0000000..30f04f1 --- /dev/null +++ b/vault/guides/writing-content.md @@ -0,0 +1,69 @@ +--- +description: Tips for writing vault content +--- + +# Writing Content + +Tips for creating great content for your BBS-MD vault. + +## File Structure + +Every `.md` file in your vault directory is a page. Subdirectories create sections: + +``` +vault/ + index.md <- Landing page (always loads first) + splash.txt <- ANSI art header (optional) + features.md <- Top-level page + guides/ + sysop-handbook.md + writing-content.md +``` + +## Frontmatter + +Add YAML frontmatter to your pages for metadata: + +``` +--- +description: A short summary shown in the directory listing +--- +``` + +The `description` field appears beside your file in the [[Directory]] listing, helping visitors find what they're looking for. + +## Linking Between Pages + +### Wiki-Links (Recommended) + +Use double-bracket syntax to link between pages: + +- `[[Page Name]]` resolves to `page-name.md` +- Case-insensitive: `[[features]]` and `[[Features]]` both work +- Cross-directory: `[[SysOp Handbook]]` finds `guides/sysop-handbook.md` + +### Standard Links + +Standard markdown links work too: + +- `[Click here](features.md)` — relative to vault root +- `[Guide](guides/sysop-handbook.md)` — path to subdirectory files + +### Special Links + +- `[[Directory]]` — opens the virtual directory listing page + +## Best Practices + +1. **Start with index.md** — it's your front door +2. **Use frontmatter descriptions** — they show up in the directory +3. **Link generously** — wiki-links make your vault navigable +4. **Keep files small** — one topic per page, like a real BBS +5. **Use all six heading levels** — they each have distinct styling +6. **Add a splash.txt** — ANSI art makes everything better + +> A well-linked vault is a joy to browse. A pile of unlinked pages is a graveyard. + +--- + +Back to [[index|home]] or browse the [[Directory]]. diff --git a/vault/index.md b/vault/index.md new file mode 100644 index 0000000..c7d282c --- /dev/null +++ b/vault/index.md @@ -0,0 +1,40 @@ +--- +description: Main landing page — start here +--- + +# Welcome to BBS-MD + +Welcome to **BBS-MD**, a retro-styled terminal markdown vault reader that brings the spirit of 1990s bulletin board systems into the modern era. Browse linked documents, explore your vault, and enjoy the warm glow of CGA colors. + +## Getting Started + +Use the keyboard to navigate this vault: + +- Press **Tab** to enter link navigation mode +- Use **Up/Down** arrows to cycle between links +- Press **Enter** to follow a link +- Press **Esc** or **Tab** again to exit link mode +- Press **Left arrow** or **Backspace** to go back + +## Explore the Vault + +Check out these pages to learn more: + +- [[Features]] — Full feature breakdown with examples +- [[Navigation Guide]] — How to navigate like a SysOp +- [[Markdown Showcase]] — See all supported markdown constructs +- [[Directory]] — Browse all documents in this vault +- [[About]] — About BBS-MD and its design philosophy +- [[Changelog]] — Version history and release notes + +## System Status + +| Component | Status | +|----------------|------------| +| Vault Engine | Online | +| ANSI Renderer | Active | +| Link Resolver | Ready | +| File Watcher | Monitoring | + +> "The BBS is dead. Long live the BBS." +> — Anonymous SysOp, 2026 diff --git a/vault/markdown-showcase.md b/vault/markdown-showcase.md new file mode 100644 index 0000000..d6b9852 --- /dev/null +++ b/vault/markdown-showcase.md @@ -0,0 +1,166 @@ +--- +description: See all supported markdown constructs in action +--- + +# Markdown Showcase + +This page demonstrates every markdown construct that BBS-MD renders. Use it as a reference or a test page. + +## Headers + +Headers from H1 through H6 each have distinct styling. H1 and H2 get decorative underlines. + +### This is H3 + +#### This is H4 + +##### This is H5 + +###### This is H6 + +## Text Formatting + +Here's **bold text**, *italic text*, and ***bold italic*** combined. You can also use ~~strikethrough~~ for deleted content. Mix them freely: ***~~all at once~~***. + +Inline `code spans` render in a distinct color for quick identification. + +## Lists + +### Unordered + +- First level item + - Second level with different bullet + - Third level goes deeper + - Back to second level +- Another top-level item + +### Ordered + +1. First step +2. Second step +3. Third step + 1. Sub-step A + 2. Sub-step B +4. Fourth step + +## Code Blocks + +### Rust + +```rust +use std::collections::HashMap; + +struct BBS { + name: String, + pages: HashMap, +} + +impl BBS { + fn new(name: &str) -> Self { + BBS { + name: name.to_string(), + pages: HashMap::new(), + } + } + + fn add_page(&mut self, slug: &str, page: Page) { + self.pages.insert(slug.to_string(), page); + } +} +``` + +### Python + +```python +class VaultReader: + def __init__(self, path: str): + self.path = path + self.pages = {} + + def load_all(self): + for md_file in Path(self.path).glob("**/*.md"): + slug = md_file.stem + self.pages[slug] = md_file.read_text() + return self +``` + +### Shell + +```bash +#!/bin/bash +# Deploy BBS-MD as a login shell +useradd -m -s /usr/local/bin/bbs-md bbsuser +mkdir -p /home/bbsuser/vault +cp -r ./demo-vault/* /home/bbsuser/vault/ +echo "BBS user created. Connect via: ssh bbsuser@localhost" +``` + +### Plain (no language) + +``` +No syntax highlighting here. +Just plain monospaced text in a box. +Useful for ASCII diagrams or raw output. +``` + +## Blockquotes + +> This is a simple blockquote. It gets a yellow pipe border on the left and gray text. + +> Multiple levels of nesting work too: +> +> > Nested blockquote. The borders stack. +> > +> > > Three levels deep. Still readable. + +## Tables + +### Basic Table + +| Planet | Moons | Ring System | +|---------|-------|-------------| +| Mercury | 0 | No | +| Venus | 0 | No | +| Earth | 1 | No | +| Mars | 2 | No | +| Jupiter | 95 | Yes | +| Saturn | 146 | Yes | + +### Aligned Columns + +| Left | Center | Right | +|:---------|:--------:|---------:| +| Alpha | Beta | Gamma | +| One | Two | Three | +| Short | Medium | Longtext | + +## Horizontal Rule + +Content above the rule. + +--- + +Content below the rule. + +## Links + +### Wiki-Links + +- [[Features]] — internal wiki-link to another vault page +- [[Directory]] — magic link to the directory listing +- [[Nonexistent Page]] — broken link shown in red strikethrough + +### Standard Links + +- [Features Page](features.md) — standard markdown link +- [Navigation](navigation-guide.md) — another standard link + +## Images + +Images render as text placeholders since we're in a terminal: + +![A beautiful sunset over the digital frontier](sunset.png) + +--- + +Back to [[index|home]]. diff --git a/vault/navigation-guide.md b/vault/navigation-guide.md new file mode 100644 index 0000000..7a536bd --- /dev/null +++ b/vault/navigation-guide.md @@ -0,0 +1,67 @@ +--- +description: How to navigate like a SysOp +--- + +# Navigation Guide + +Master the keyboard and browse your vault like a true SysOp. + +## Scrolling + +| Key | Action | +|--------------|---------------------| +| `j` / Down | Scroll down one line | +| `k` / Up | Scroll up one line | +| `PgDn` | Scroll down one page | +| `PgUp` | Scroll up one page | + +## Link Navigation + +BBS-MD uses a **modal link navigation** system: + +1. Press **Tab** to enter link mode +2. A highlight appears on the first link +3. Use **Up/Down** arrows (or `j`/`k`) to cycle between links +4. Press **Enter** to follow the selected link +5. Press **Tab** or **Esc** to exit link mode + +> In link mode, the status bar updates to show link-specific hints. Watch the bottom of your screen for context. + +## Page Navigation + +| Key | Action | +|------------------|---------------------| +| Left / Backspace | Go back in history | +| Right | Go forward in history | +| Alt+Left | Go back (always) | +| Alt+Right | Go forward (always) | + +History works like a web browser. Following a new link from a mid-history position forks the history — forward entries are discarded. + +## Directory Page + +The [[Directory]] page behaves differently: + +- You're **always** in link mode on the directory page +- Up/Down arrows cycle through document entries +- Enter opens the selected document +- **Esc** navigates back to the previous page +- Tab has no effect (link mode can't be toggled off) + +## Quitting + +| Key | Action | +|----------------|-----------------------------------| +| `q` | Quit immediately (normal mode) | +| `Ctrl+C` x2 | Quit with confirmation (always) | + +In **login shell mode**, `q` is disabled. You must use double `Ctrl+C` to disconnect. + +## Tips + +- The **breadcrumb** in the status bar shows your current location +- **File metadata** (last modified date and size) appears on the right side of the status bar +- Links that can't be resolved appear in ~~red strikethrough~~ +- The vault is **live** — edit a file externally and the page refreshes automatically + +Back to [[index|home]] or see [[Features]]. diff --git a/vault/splash.txt b/vault/splash.txt new file mode 100644 index 0000000..3a5a517 --- /dev/null +++ b/vault/splash.txt @@ -0,0 +1,8 @@ +[1;36m ____ ____ ____ __ __ ____ [0m +[1;36m| __ )| __ )/ ___| | \/ | _ \ [0m +[1;36m| _ \| _ \\___ \ _____| |\/| | | | |[0m +[1;36m| |_) | |_) |___) |_____| | | | |_| |[0m +[1;36m|____/|____/|____/ |_| |_|____/ [0m +[0;33m───────────────────────────────────────[0m +[1;33m Retro BBS Markdown Vault Reader v1.0[0m +[0;33m───────────────────────────────────────[0m