Skip to main content

RABS Documentation Style Guide

This guide defines exact formatting rules for all documentation in the RABS project. It ensures consistency, readability, and correct rendering on GitHub — whether authored by a human or generated by a language model.

Purpose​

This style guide exists to:

  • Ensure reliable GitHub rendering (headings, bullets, spacing)
  • Create consistency across all project documentation
  • Enable accurate output from AI agents or scripted generators
  • Avoid formatting issues when pasting into GitHub’s editor or web UI

Markdown Formatting Rules​

1. Headings​

  • Use real #, ##, or ### — not bold text
  • Always leave a blank line after each heading

Example:

## Frontend Strategy

Details go here...

2. Bullet Lists​

  • Use - for bullets — never use •, ·, or *
  • Leave a blank line above and below bullet blocks
  • For long bullets, leave a blank line between them
- This is a valid bullet

- So is this

3. Horizontal Rules​

Use three dashes to divide major sections.

---

4. Inline Emphasis​

Use Markdown formatting conventions:

  • **bold** for filenames, terms, or emphasis
  • *italics* for tone or nuance
  • `inline code` for filenames, prompt labels, and references

Example:

Reggie uses `prompt.js` and pulls fallback from `modelMatrix.json`

End each README or .md file with:

## 🔗 Additional Docs

- docs/system-architecture.md
- docs/agent-design-principles.md
- docs/reggie-is-alive.md

Output Instructions for Language Models (LLMs)​

When generating Markdown for the RABS project:

  1. Use only valid Markdown syntax (#, -, etc.)
  2. Avoid triple backticks unless inside an actual code block
  3. Never wrap the full document in a code block
  4. Leave one blank line after headings and between bullets
  5. Do not use smart quotes or long dashes (“ ” —) — use " " and --
  6. Always end with a proper ## 🔗 Additional Docs section

Template for LLM-Generated Markdown​

# Document Title

## Section Heading

- Bullet one
- Bullet two

---

## Next Section

Explanation text...

## 🔗 Additional Docs

- link1.md

✅ Do not wrap this in backticks. Output raw Markdown only.

  1. # Title + Summary
  2. ## Core Functional Areas
  3. ## Frontend Strategy
  4. ## Development Environment
  5. ## Novel Concepts and Innovations
  6. ## Areas in Progress / Next Steps
  7. ## 🔗 Additional Docs

Common Mistakes to Avoid​

ProblemFix
Using • or · instead of -Always use - for bullets
No spacing after headingsLeave a blank line after each heading
Fake headers using bold textUse real Markdown headers (#, ##)
Wrapping the whole doc in backticksNever wrap a full doc unless it’s inside a code block
Curly quotes or em-dashesReplace with " " and --

Markdown Syntax Reference (Cheat Sheet)​

Headings​

# Heading 1
## Heading 2
### Heading 3

Text Styles​

**Bold**
*Italic*
~~Strikethrough~~

Inline & Block Code​

`inline code`

```js
// Code block with language hint
console.log('Hello');

### Lists

```markdown
- Bullet
- Bullet

1. Numbered
2. Numbered

Blockquote​

> This is a quote

Link & Image​

[OpenAI](https://openai.com)

![Alt text](https://via.placeholder.com/100)

Table​

| Header | Value |
|--------|-------|
| Row A  | ✅    |
| Row B  | 💡    |

Horizontal Rule​

---

✅ Follow this style and every doc will render properly, pass peer review, and be compatible with GitHub, diff tools, and AI generation workflows.