ruohki/bbs-md
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

content: create demo vault with splash art and feature showcase pages

Browse Source 
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.
This commit is contained in:
ruohki
2026-03-01 11:58:01 +01:00
parent f3d787a2b7
commit 4464774c7a
9 changed files with 641 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vault/about.md
+71
View File
@@ -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]].
vault/changelog.md
+64
View File
@@ -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]].
vault/features.md
+77
View File
@@ -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]].
vault/guides/sysop-handbook.md
+79
View File
@@ -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]].
vault/guides/writing-content.md
+69
View File
@@ -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]].
vault/index.md
+40
View File
@@ -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
vault/markdown-showcase.md
+166
View File
@@ -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<String, Page>,
}
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]].
vault/navigation-guide.md
+67
View File
@@ -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]].
vault/splash.txt
+8
View File
@@ -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