# Getting Started

A quick tour of how to use this documentation site.

# Welcome — read this first

## Welcome to CA UK docs

This is where we document how the CA UK websites work, how the different JSON feeds talk to each other, and anything else worth writing down.

### How content is organised

BookStack uses a four-level hierarchy:

- **Shelves** — optional groupings that hold multiple books.
- **Books** — the main unit. One book per subject (e.g. "National website", "District shop").
- **Chapters** — optional sub-sections within a book.
- **Pages** — the actual content.

### Logging in

Click **Log In** at the top right. Public visitors can read content without logging in.

### Next steps

1. Read *Writing your first page* to learn the editor.
2. Read *Diagrams and images* to see how to draw architecture diagrams directly in a page.
3. Read *Organising content* to learn about books, chapters, and permissions.

# Writing your first page

## Creating a page

1. Open a book (or create one from the home page).
2. Click **New Page**.
3. Give it a name at the top.
4. Write your content in the editor.
5. Click **Save Page**.

## WYSIWYG vs Markdown

BookStack has two editors. Pick one per page:

- **WYSIWYG** (default) — rich-text editor, like Google Docs.
- **Markdown** — plain text with `**bold**`, `# headings`, etc.

## Basic formatting

- **Bold** — `Ctrl/Cmd + B`
- *Italic* — `Ctrl/Cmd + I`
- Headings — dropdown in the toolbar
- Code blocks — use the `</>` button (JSON, PHP, JS, etc.)
- Links — highlight text and press `Ctrl/Cmd + K`

## Linking to other pages

Paste any BookStack URL into the editor and it auto-converts to a nice link.

# Diagrams and images

## Drawing diagrams

BookStack has **diagrams.net** (formerly drawio) built in. This is the killer feature for documenting how systems connect.

### How to insert one

1. In the editor toolbar, click the diagrams button.
2. A drawio window opens. Draw your diagram.
3. Click **Save**. The diagram is embedded but stays editable — click it later to re-open.

### What to draw

- System architecture (boxes = services, arrows = data flows)
- Sequence diagrams (who calls whom)
- Data flow between JSON feeds and the websites that consume them
- Deployment diagrams

## Images

Drag-and-drop images into the editor. They upload automatically.

## Code and JSON

Use the code block button (`</>`) and pick the language. All syntax-highlighted.

# Organising content and permissions

## Creating books

Click **New Book** from the home page. Give it a name and description.

## Chapters

Inside a book, click **New Chapter**. Use chapters when a book has 20+ pages.

## Moving pages

Open a page → **Edit** → cog menu → **Move Page**.

## Permissions

The site is currently **public** — anyone can read without logging in.

### Making something private

1. Open the shelf, book, chapter or page.
2. Click **Edit** → **Permissions**.
3. Enable *Custom permissions*.
4. Remove the **Public** role from View etc.

Permissions cascade down.

## Searching

Top-bar search indexes everything. Use `tag:feeds` to filter by tag.