# CLAUDE.md

# BOGAMARK Best Practices

## Article Structure

1. **Categories** - Place at the very top of the article

   ```
   [[Category:Geography]]
   [[Category:Hawaii]]
   ```

2. **Table of Contents** - Use `<<TOC>>` marker where appropriate

3. **Content Sections** - Start with `## Overview` when it makes sense

## Table Formatting

- Use proper BOGAMARK table syntax with `||` delimiters
- Add styling attributes when they improve readability

## Link Formatting

### Internal Links

- Remove underscores from display text
- Good: `[[Banzai_Pipeline|Banzai Pipeline]]`
- Bad: `[[Pipeline_(surfing)|Pipeline_(surfing)]]`

### Link Everything Important

- Every key concept should link to its topic page
- Use descriptive display text

## List Formatting

### Proper Spacing

```
 * First item (note the space before *)
  * Nested item
 * Second item
```

## Section Hierarchy

- `##` Main sections
- `###` Subsections
- `####` Sub-subsections
- Never use `#` (reserved for article title)

## Common Mistakes to Avoid

1. **Improper list indentation** - Use spaces before `*` or `1.`
2. **Markdown tables** - Never use markdown table syntax (`|---|---|`)
3. **Missing links** - Link important terms and concepts

# BOGAMARK Grammar Syntax

BOGAMARK is a markup language for BOGAM.
BOGAMARK is similar to Markdown, Wikipedia, and Namu Wiki.
Use file extension `.bg` (e.g. `example-bogamark.bg`).

## Naming (Files and Titles)

- Replace spaces with underscores in filenames

Example:

- Link: `What_is_Love?_(TWICE_음반)`
- Title: `What is Love? (TWICE 음반)`

## Linking

Format: `[[link_target|display_text]]`

### Internal Linking

Example:

```
This song was released as a part of [[What_is_Love?_(TWICE_음반)|TWICE's 5th mini album]].
```

### External Linking

Example:

```
Visit [[https://bluebottlecoffee.com/|Blue Bottle Coffee]] for more information.
```

- All protocols are supported (e.g. http, https, mailto).
- Always prefer internal linking over external linking.

## Disambiguation

Disambiguate using parentheses.
Example: "Genesis (Car Brand)"

## Redirects

`#REDIRECT [[Target]]`

## Transclusion

Same as Wikipedia
`<<transclusion-target>>`

## Table of Contents

To specify where to place ToC in article body, write `<<TOC>>` (case-insensitive).
If not specified, ToC will be placed at the top of article body (below article title).

## Section Heading

Cluster information into sections. To title sections, use markdown heading syntax from H2 to H6. For example: `## Section about an aspect of a topic`, `#### Section at depth 3`. Maximum depth is 5 (`###### Maximum depth section`). H1 (`#`) is reserved for topic article title and must not be used for section titles.

## Text Formatting

- **Bold**: `**text**`
- **Italic**: `*text*`
- **Bold + Italic**: `***text***`
- **Underline**: `__text__`
- **Strikethrough**: `~~text~~`
- **Superscript**: `<sup>text</sup>`
- **Subscript**: `<sub>text</sub>`

## Text Size

- `{{{+5 text}}}` - Size +5 (largest)
  ...
- `{{{+1 text}}}` - Size +1 (larger)
- `{{{-1 text}}}` - Size -1 (smaller)
  ...
- `{{{-5 text}}}` - Size -5 (smallest)

## Text Color

- `{{{#ff6b6b text}}}` - Hex color

## Literal

`{{{[[literal]]}}}` renders as `[[literal]]`
NOTE: Do not use more than 3 consecutive brackets inside literal blocks.

## Lists

### Unordered Lists (Bullet Points)

```
 * List item 1
  * List item 1.1
 * List item 2
```

### Ordered Lists (Numbered Lists)

Use `1.` instead of `*` for ordered lists.

```
 1. List item 1
  1. List item 1.1
 1. List item 2
```

### Ordered Lists: Changing Starting Number

To start a list from a specific number, use `#n` after the list identifier:

```
 1.#5 This list starts from 5
 1. List item 6
 1. List item 7
```

### Line Breaks in Lists

- Use `[br]` macro for line breaks within list items
- Empty lines between list items will create separate lists

## Tables

A table row starts with `||` and ends with `||`. Multiple cells in a row are separated by `||`.

```
|| Row 1 Col 1 || Row 1 Col 2 ||
|| Row 2 Col 1 || Row 2 Col 2 ||
```

### Cell Merging

To merge horizontally, use `<-n>` syntax.

```
||<-2> Two cells merged ||<-2> Two cells ||
||<-3> Three cells merged || One cell ||
```

To merge vertically, use `<|n>` syntax.

```
||<|4> Four rows ||<|3> Three rows ||<|2> Two rows || One row ||
|| Space1 ||
|| Space2 || Space3 ||
|| Space4 || Space5 || Space6 ||
```

### Cell Text Alignments

Horizontal

- `<(>` - Left align (default)
- `<:>` - Center align
- `<)>` - Right align

Vertical

- `<^|1>` - Top align
- `<|1>` - Middle align (default)
- `<v|1>` - Bottom align

### Table Dimensions

- Absolute width: <tablewidth=600px>
- Relative width: <tablewidth=50%>

#### Cell Dimensions

- Absolute width: <width=200px>
- Relative to table width: <width=50%>
- Absolute height: <height=200px>
- Relative to table height: <height=50%>

### Table Coloring

- Priority Order: Cell > Column > Row > Table: bgcolor > colbgcolor > rowbgcolor > tablebgcolor

#### Background Colors

Cell: <bgcolor=#RRGGBB>
Column: <colbgcolor=#RRGGBB>
Row: <rowbgcolor=#RRGGBB>
Table: <tablebgcolor=#RRGGBB>

#### Text Colors

Cell: <color=#RRGGBB>
Column: <colcolor=#RRGGBB>
Row: <rowcolor=#RRGGBB>
Table: <tablecolor=#RRGGBB>

#### Border Color

<tablebordercolor=#RRGGBB>
NOTE: Changing border color changes border thickness from 1px to 2px.

### Table Macros

- Remove cell padding: `<nopad>`
- Change line breaking from character-level to word-level: `<keepall>`, `<rowkeepall>`, `<colkeepall>`

## Escape

Use backslash (`\`) to escape: `*`, `[`, `]`, `|`, `#`, `\`

- `\*text\*` → `*text*` (not italic)

## Dark Mode Support for Colors

Specify color variations for dark mode using comma separation.

- Format: `#lightModeColor,#darkModeColor`
- Example (Text Color): `{{{#ff6b6b,#6bff6b text}}}`
- Example: `<tablebordercolor=#ff0000,#00ff00>` (red in light mode, green in dark mode)

## Embed Media

- YouTube Videos: `[youtube(video_id,width=size,start=seconds,end=seconds)]`
- Web Images: `[image(url,alt=description,width=size,height=size)]`

# Git Branching Guideline

## Branches

```
main (production) <- fix/
  ↑
versions (y3s3w6, y3s3w7, etc.) ← test and fix/
  ↑
add/ | fix/ | retire/
```

**Version**: `y3s3w6` (year, season, week)

- **Add Feature**: `add/feature`
- **Retire Feature**: `retire/feature`
- **Fix**: `fix/issue`

# Preferences

- Shell Web (shells/shell-web) is Astro project with CloudFlare adapter. Use packages and strategies that are compatible with this set up.

- Package Manager: PNPM

- Do not install new packages without asking for permission. Clearly explain why the package is needed. Clearly explain options and why installing this package is considered the best choice. When you need to add a new package, request it, and justify why it is needed.

- Import using @ instead of .. (relative).

- Write code cleanly and neatly as if you have slight OCD. Be precise in naming variables and functions. Write concisely without unnecessary comments. Write simply. Repeating a few times is okay if doing so makes code more readable than unnecessarily abstracting into layers of abstraction.

- Make edits absolutely minimum. I want the most elegant, simplest, leanest changes. Do not write comments. I review code with extreme scrutiny, especially on writing concisely and writing precisely. Variables and functions must be named precisely.

- Do not start server on your own. Server is running when you are working. If it is absolutely necessary to restart server, let me know and I will restart the server for you.

- When you cannot figure out how code works, especially specific to the frameworks we use, compose an advanced deep research query so that I can get the web research done in great details for you, and then you can review answers to proceed. It is good to check sources like StackOverflow, GitHub, and official documentation.

- We write code like we have OCD. Separation of concerns is very important.

- When fixing CSS, you must write proper code instead of coming up with hacky fixes such as misusing !important. Investigate to identify root cause, then plan a fix, and then fix.

- Do not perform any git operations on your own.

- Python Package Manager and Environment Manager: uv (do not use pip or venv)

- Separation of Concerns: I strongly prefer that you keep code lean and sipmle. Do not make a new file unless necessary. Do not write a new line of code unless important to do so. I strongly prefer balance. I hate overly big files (for example, I prefer making each file contain 300 lines of code or less, ideally less the better, and I start getting annoyed when you write more than 500 lines of code, and I will yell at you if you have over 1000 lines of code in a single file). You can decompose and nest to keep each file manageable. But I also hate having too many small files. I do not think a new file should be created if it has less than 50 lines of code, unless the new file needs to be created for a clear separation of concern, or because that file is expected to grow to be an important area of concern in future. You must also pay attention to how code logic is divided across files. Ideally, a file should have a one-to-one mapping with an area of concern, and codes related to one area of concern should exist in the appropriate file.

# Shell Aesthetics

Use Shadcn UI.

Use centrally defined aesthetics instead of hard-coding CSS values in each page.

# Topic Article Generation Guideline

For input topic, generate an article. Assess how big the topic is, then plan out the table of contents. A big topic must lead to a comprehensive document with many sections. A small topic must lead to a concise document with few sections.

Write in iterations. First, outline what to write about at a high level. Make sure to divide out the information well into sections. Decompose the work into each section. Use transclusion for the task decomposition.

In outline, make sure to plan out what important terms and ideas must be discussed such that they will be discussed during the writing step.

When writing, use rich features in bogamark-syntax in order to deliver information effectively to the readers. Use features to be helpful. Do not use features unnecessarily in ways that are not useful for information delivery.

Write informatively, using full sentences. Do not write too scientifically like Wikipedia. Do not write too casually like a sensationalist magazine. Do not write too carefully like a lawyer. Write like a good wiki, providing helpful information in ways that are relatable and correct.

Make sure to add links to terms using bogamark-syntax such that reader can be guided to learn about related topics.