---
name: markdown-book-references-html
description: Annotate a multi-part Markdown book with numbered scientific reference markers [1]–[N] throughout and a unified References section. Also export to HTML with dark theme CSS.
version: 1.0
author: Hermes
tags: [markdown, references, bibliography, html-export, book, annotation]
---

## When to use
User has a large Markdown document (book, paper, or multiple parts) that references scientific works, physics laws, and academic papers. They want:
1. Numbered reference markers `[1]`, `[2]`… throughout the text (like in books)
2. A full References section at the end with author, title, journal, year
3. (Optional) A professional HTML export with dark theme

## Workflow

### 1. Inventory all files
Use `search_files` across the project directory to find all `.md` files. Common patterns: `*часть*`, `*part*`, `*книг*`.

### 2. Build a reference database
Create a Python structure:
```python
refs = [
    ("[N]", "Author. Title // Journal. Year. Vol. P.", ["regex_patterns"]),
]
```
Standard physics sources: Boltzmann, Einstein (1905, 1916), Planck (1900), Heisenberg (1927), Schrödinger (1935), Everett (1957), Wheeler (1989), Hawking (1975), Poincaré, Perelman, Aspect (1982), Zeilinger, 't Hooft, Susskind, Guth, Penzias & Wilson (1965). Neuroscience: Moruzzi & Magoun (RAS, 1949), Merzenich (neuroplasticity, 1983), Crick & Koch (1990), Dehaene (2011), Tononi (IIT, 2004), Raichle (DMN, 2001). Information: Shannon (1948), Turing (1936).

### 3. Insert markers via execute_code
- Read the book with `open(path, encoding='utf-8')` (NOT `read_file` — it adds line numbers)
- Split into lines, process each
- For each reference, find matching lines with `re.search(pattern, line, re.IGNORECASE)`
- Insert marker AFTER the anchor text: `new_line = line[:idx+len(anchor)] + " " + marker + line[idx+len(anchor):]`
- **Critical:** check that the anchor isn't ALREADY followed by a `[N]` marker: `if not re.match(r'\[\d+', after_text)`
- Skip if the line already contains any `[N]` marker

### 4. Handle edge cases
- **TOC with Markdown links:** Place marker OUTSIDE: `[text](url) [1]`, never `[text [1]](url)`
- **Multi-concept lines:** Append all relevant markers: `"...запутанности [4] и голографии [7][8]..."`
- **Already-annotated zones:** Track with line ranges (e.g., Part 4 was done separately, skip lines 2700–3550)

### 5. Merge multi-part books
```python
files = [("Name", "/path/to/file.md"), ...]
for title, path in files:
    with open(path, encoding='utf-8') as f:
        content = f.read()
    merged.append(f"\n{'='*70}\n\n{content}")
```

### 6. Replace/add unified References section
```python
old_idx = content.rfind("## 13. Список научных")
if old_idx > 0:
    content = content[:old_idx] + unified_refs_block + content[end_idx:]
```
Group by category: Physics & Cosmology, Neuroscience, Philosophy of Science.

### 7. Convert to HTML (if needed)
When sandbox Python lacks `markdown` library, use system Python:
```python
import subprocess
script = '''
import markdown
html = markdown.markdown(md_content, extensions=['tables','fenced_code','toc'])
with open(output_path, "w") as f: f.write(template % html)
'''
subprocess.run(["/usr/local/bin/python3", "-c", script], timeout=30)
```
On macOS, system Python is at `/Library/Frameworks/Python.framework/Versions/3.12/bin/python3`.

### 8. HTML template
Dark theme with CSS variables:
- `--bg: #0d0d0d`, `--text: #e0e0e0`, `--accent: #e67e22`
- Headers: `h1` gold (`#f39c12`), `h2` amber with left border, `h3` dark orange
- Code: dark background `#1a1a1a`, green text `#a5d6a7`
- Blockquotes: italic, amber border-left, dark blue bg
- Tables: striped rows, amber headers
- Print styles: switch to white bg/black text
- Responsive: `max-width: 900px`, mobile at 700px

## Pitfalls
- `read_file` results include line numbers — use `open()` for raw content
- Regex with Cyrillic: use `re.IGNORECASE`, watch for `е/ё` variations (декогеренция vs декогеренция)
- URL-breaking: never insert markers inside `[text](url)` parentheticals
- Duplicate markers: always check `after_text` before inserting
- Sandbox Python may not have libraries — find system Python with `which python3` or known macOS path
