Editing Standards

Meta-Editing Standards

These standards ensure consistent formatting across all NeuroWiki pages. Follow them exactly.

Markdown Basics

Headings

Top-Level Heading (Page Title)

Section Heading

Subsection Heading

Deep Subsection

• Only one H1 per page (the title)
• Use H2 for major sections, H3 for subsections
• Don't skip heading levels (don't go H2 → H4)

Bold and Italic

Bold for emphasis Italic for book titles, foreign words Bold Italic for strong emphasis

Reference Formatting

Frontmatter References

All references go in the YAML frontmatter:

title: "Page Title"
description: "Description here"
refs:
smith2023:
authors: "Smith J, Jones M"
title: "Paper Title"
journal: "Nature Neuroscience"
year: 2023
pmid: "12345678"
doe2024:
authors: "Doe J, et al."
title: "Another Paper"
journal: "Lancet Neurology"
year: 2024
doi: "10.1234/example"

Required fields: `title`, `year` At least one of: `pmid`, `doi`, `url`

Inline Citations

Use `[@citekey]` in the body:

Alzheimer's disease affects millions[@smith2023].
Novel treatments show promise[@doe2024].

The sync pipeline converts these to numbered footnotes.

Reference Links

Always hyperlink DOIs and PMIDs:

[Smith et al., Amyloid cascade (2023)](https://pubmed.ncbi.nlm.nih.gov/12345678/)

[Doe et al., Novel therapy (2024)](https://doi.org/10.1234/example)

Never write: `DOI: 10.1234` or `PMID:12345678`

Link Syntax

...

Meta-Editing Standards

These standards ensure consistent formatting across all NeuroWiki pages. Follow them exactly.

Markdown Basics

Headings

Top-Level Heading (Page Title)

Section Heading

Subsection Heading

Deep Subsection

• Only one H1 per page (the title)
• Use H2 for major sections, H3 for subsections
• Don't skip heading levels (don't go H2 → H4)

Bold and Italic

Bold for emphasis Italic for book titles, foreign words Bold Italic for strong emphasis

Reference Formatting

Frontmatter References

All references go in the YAML frontmatter:

title: "Page Title"
description: "Description here"
refs:
smith2023:
authors: "Smith J, Jones M"
title: "Paper Title"
journal: "Nature Neuroscience"
year: 2023
pmid: "12345678"
doe2024:
authors: "Doe J, et al."
title: "Another Paper"
journal: "Lancet Neurology"
year: 2024
doi: "10.1234/example"

Required fields: `title`, `year` At least one of: `pmid`, `doi`, `url`

Inline Citations

Use `[@citekey]` in the body:

Alzheimer's disease affects millions[@smith2023].
Novel treatments show promise[@doe2024].

The sync pipeline converts these to numbered footnotes.

Reference Links

Always hyperlink DOIs and PMIDs:

[Smith et al., Amyloid cascade (2023)](https://pubmed.ncbi.nlm.nih.gov/12345678/)

[Doe et al., Novel therapy (2024)](https://doi.org/10.1234/example)

Never write: `DOI: 10.1234` or `PMID:12345678`

Link Syntax

Internal Wiki Links

Correct format:
[Display Text](/path/to/page)

Examples:

• `[APP Gene](/entities/app)`
• `[Alpha-Synuclein](/proteins/alpha-synuclein)`
• `[Alzheimer's Disease](/diseases/alzheimers-disease)`

Path prefixes:

• `/entities/` — genes, proteins
• `/diseases/` — diseases
• `/mechanisms/` — pathways
• `/cell-types/` — cell types
• `/treatments/` — therapeutics
• `/clinical-trials/` — trials
• `/researchers/` — scientists
• `/institutions/` — universities, hospitals

Rules:

• Use entity name as link text, not descriptions
• CORRECT: `[APP](/entities/app)`
• WRONG: `[the gene](/entities/app)`
• Link once per section, not every mention

External Links

[Display Text](https://example.com)

Entity Names

Standard Naming Conventions

| Entity | Format | Example |
|--------|--------|---------|
| Gene | "GeneName Gene" | "LRRK2 Gene" |
| Protein | "ProteinName" | "Alpha-Synuclein" |
| Disease | "Disease Name" | "Alzheimer's Disease" |
| Mechanism | "Mechanism Name" | "Amyloid Cascade" |
| Cell Type | "Cell Type Name" | "Microglia" |
| Therapeutic | "Drug Name" | "Donepezil" |

Links to Entities

Always use the standard page path:

• Gene pages: `/entities/gene-name`
• Protein pages: `/proteins/protein-name`
• Don't mix formats

Cross-Linking Best Practices

Link first meaningful mention — Not every mention

Use descriptive link text — `[APP](/entities/app)` not `[this protein](/entities/app)`

Include See Also section — Link to 3-10 related pages

Bidirectional links — If you link to X, X should link back

Mermaid Diagrams

For pathway visualizations:

Rules:

• Labels in `["double quotes"]`
• Node IDs are short (A, B, C)
• Use color fills appropriately
• Test before publishing

What NOT to Do

Never Do These

• Don't use numeric citations like `[1]` in body text
• Don't leave orphan brackets `[text]` without a URL
• Don't nest brackets `[text [more]](url)` breaks parsing
• Don't use bare DOIs — Always hyperlink: `[DOI](https://doi.org/...)`
• Don't create sections off root path — Always use section prefixes

Common Errors to Avoid

| Error | Correction |
|-------|------------|
| `[Gene](/genes/app)` | `/entities/app` (no /genes/) |
| `PMID:12345` | `PMID: 12345(https://pubmed.ncbi.nlm.nih.gov/12345/)` |
| `# Section` | `## Section` (use >= H2) |
| `[text](url` | `[text](url)` (closed parens) |

Validation Tools

Before publishing, run:

Check references

python3 scripts/reference_lint.py --check path/to/page.md

Check links

python3 scripts/link_fixer.py audit --path path/

Check markdown

python3 scripts/mermaid_lint.py --check path/to/page.md

Quick Reference Card

| Category | Standard |
|----------|----------|
| Title | "LRRK2 Gene" |
| Link | `[LRRK2](/entities/lrrk2)` |
| Ref | `[@citekey]` in body |
| Heading | `## Section Name` |
| Ref link | `[PMID](https://pubmed.ncbi.nlm.nih.gov/...)` |

See Also

• [Changelog Format Guide](/Meta/changelog-format-guide)
• [Content Contribution Guide](/Meta/content-contribution-guide)
• [Quality Checklist](/Meta/quality-checklist)