Markdown Template Guide

This document explains the markdown template structure and cross-referencing system implemented in this project. For related information, see ../core/how-to-use.md for usage guidance, ../core/architecture.md, ../core/workflow.md, and ../README.md.

Template Structure

The template demonstrates an academic paper structure organized as numbered markdown sections.

Note: The section file names, section labels ({#sec:...}), and the eq:/fig: labels listed throughout this guide are illustrative naming patterns, not the literal contents of any one exemplar. The canonical template_code_project ships 00_abstract.md, 01_introduction.md, 02_methodology.md, 03_results.md, 04_conclusion.md, 05_experimental_setup.md, 06_reproducibility.md, 07_scope_and_related_work.md, and 99_references.md (plus preamble.md). List the real files for your checkout with ls projects/templates/template_code_project/manuscript/.

Core Sections (illustrative)

manuscript/preamble.md - LaTeX preamble with styling and packages
manuscript/00_abstract.md - Research overview and key contributions
manuscript/01_introduction.md - Introduction with section references and overview
manuscript/02_methodology.md - Mathematical framework with numbered equations
manuscript/03_results.md - Results with figure and equation references
manuscript/04_conclusion.md - Conclusion summarizing all contributions
manuscript/05_experimental_setup.md - Experimental setup and methodology details
manuscript/06_reproducibility.md - Reproducibility and code availability
manuscript/07_scope_and_related_work.md - Scope and related work
manuscript/99_references.md - Bibliography and references

Cross-Referencing System

Section References

Use [@sec:section_name] to reference sections — never raw \ref{} or a Markdown filename link (see Manuscript Semantics):

# Introduction {#sec:introduction}

The methodology described in [@sec:methodology] shows...

Labels are project-owned. Discover the current set instead of copying this guide's examples:

rg -n '\{#sec:' projects/templates/template_code_project/manuscript/

Equation References

Use [@eq:equation_name] to reference equations — never raw \eqref{}:

$$
\|x_k - x^*\| \leq C \rho^k
$$ {#eq:convergence}

The convergence rate [@eq:convergence] shows...

Equation labels are likewise project-owned. Inspect them with rg -n '\{#eq:|\\label\{eq:' projects/<qualified-name>/manuscript/.

Figure References

Use [@fig:figure_name] to reference figures — never raw \ref{}:

![Experimental setup diagram.](../output/figures/experimental_setup.png){#fig:experimental_setup width=80%}

[@fig:experimental_setup] shows the pipeline...

Figure labels are declared by each manuscript and its generated figure registry. Inspect both before adding a reference; do not assume an illustrative label exists.

Table References

Use [@tbl:table_name] to reference tables — never raw \ref{}:

| Metric | Value | Unit |
|--------|-------|------|
| Performance | {{PERFORMANCE_VALUE}} | {{PERFORMANCE_UNIT}} |

: Performance summary. {#tbl:performance_summary}

[@tbl:performance_summary] shows...

Equations and Cross-References

Equation Forms

The template supports two equivalent forms for a labelled display equation — the pure-Pandoc form is preferred; the raw-LaTeX equation environment also works because pandoc-crossref picks up \label{}:

$$
f(x) = \sum_{i=1}^{n} w_i \phi_i(x)
$$ {#eq:example}

Mathematical Notation

Examples of mathematical notation used:

Greek letters: $\alpha$, $\beta$, $\lambda$, $\rho$, $\epsilon$
Mathematical operators: $\min$, $\max$, $\sum$, $\prod$
Special symbols: $\mathbb{R}$, $\mathcal{X}$, $\nabla$
Subscripts/superscripts: $x_k$, $x^*$, $w_i$

Cross-References in Text

Demonstrates various cross-reference patterns:

- Section references: [@sec:methodology]
- Equation references: [@eq:convergence]
- Figure references: [@fig:convergence_plot]
- Multiple references: [@eq:objective] through [@eq:convergence]

Figure Generation

Scripts

The template includes two figure generation scripts that demonstrate the thin orchestrator pattern:

projects/{name}/scripts/<analysis>.py - Thin orchestrator (code exemplar: optimization_analysis.py) using projects/{name}/src/ methods
projects/{name}/scripts/y_generate_* - Optional ordered figure/analysis scripts (prose exemplar pattern)

Thin Orchestrator Pattern

Scripts in the scripts/ directory are thin orchestrators that:

Import mathematical functions from projects/{name}/src/ modules
Use tested methods for all computation (never implement algorithms)
Handle visualization, I/O, and orchestration
Generate figures and data outputs
Validate that projects/{name}/src/ integration works correctly

Example integration:

# When the script adds its project root to sys.path, import the project package.
from src.optimizer import compute_gradient, quadratic_function

def generate_figure():
    # Use projects/{name}/src/ methods for all computation
    data = [-2.0, -1.0, 0.0, 1.0, 2.0]
    gradients = [compute_gradient([value])[0] for value in data]
    objectives = [quadratic_function([value]) for value in data]

    # Script handles visualization and output
    fig, ax = plt.subplots()
    ax.plot(data, objectives, label="Objective")
    ax.plot(data, gradients, label="Gradient")
    ax.legend()
    return fig

Output Structure

Project analysis scripts save outputs to:

projects/<qualified-name>/output/figures/ - figure files and registry
projects/<qualified-name>/output/data/ - data, manifests, and manuscript variables

Integration

Figures are referenced in markdown using relative paths, Pandoc image syntax, and a {#fig:name} attribute:

![Figure caption.](../output/figures/figure_name.png){#fig:figure_name width=80%}

Source-injected manuscript variables

Any value that can change when data, configuration, code, or analysis changes must be a {{TOKEN}} in source manuscript files. This includes statistics in prose, tables, visible captions, annotations, and accessibility descriptions. The canonical flow is:

tested project src + config + analysis outputs
  -> project manuscript-variable producer
  -> output/data/manuscript_variables.json
  -> write_resolved_manuscript_tree(...)
  -> output/manuscript/*.md
  -> enabled renderers

The pipeline normally hydrates this render tree before rendering. The control-positive exemplar's producer is projects/templates/template_code_project/scripts/z_generate_manuscript_variables.py; its default mode fails if required analysis outputs are missing. Use its --allow-draft option only for an intentional early draft.

Do not hand-edit manuscript_variables.json or hydrated files under output/manuscript/. Extend the project-owned producer, regenerate, and fail validation if a required token is unresolved. Keep visible captions distinct from concise registry alt text, with longer descriptions in nearby prose when the visualization is complex. See Manuscript Semantics.

Validation System

Manuscript Validation

Markdown validation is performed via the infrastructure validation module:

uv run python -m infrastructure.validation.cli markdown \
  projects/templates/template_code_project/manuscript/

This checks:

Image file existence
Equation label uniqueness
Cross-reference validity
No bare URLs

Glossary Generation

Glossary generation is not a fixed numbered pipeline stage in the root scripts/ DAG; run it manually when needed (see modules guide):

uv run python -m infrastructure.documentation.generate_glossary_cli \
  projects/templates/template_code_project/src/ projects/templates/template_code_project/manuscript/98_symbols_glossary.md

This:

Scans the given src/ tree for public APIs
Generates a markdown table
Injects it into the target manuscript file (created if missing)

Build Process

Pipeline

The pipeline orchestrator (./run.sh pipeline or the compatibility entry point scripts/runner/execute_pipeline.py):

Runs tests with coverage requirements (90% project, 60% infra)
Executes scripts to generate figures and data (validating projects/{name}/src/ integration)
Hydrates manuscript variables into the output render tree
Validates manuscript for references and images
Builds enabled formats from the hydrated sources
Validates and copies deliverables and evidence

Output Files

Generated outputs include:

Enabled PDF, HTML, slide, DOCX, and EPUB artifacts (see Output formats)
Intermediate LaTeX and combined markdown used by renderers
Figures and data files
Coverage reports

Best Practices

Writing New Sections

Add section label: # Section Title {#sec:section_name}
Use descriptive equation labels: {#eq:descriptive_name}
Reference previous content: Use [@sec:name] and [@eq:name] — never raw \ref{}/\eqref{}
Include figures: Reference generated figures with [@fig:name]

Adding Equations

Use a labelled display block: $$ ... $$ {#eq:name} (or \begin{equation}\label{eq:name}...\end{equation})
Choose descriptive labels: Avoid generic names like eq:1
Reference consistently: Use [@eq:name] throughout — never \eqref{}

Creating Figures

Generate with scripts: Use scripts in the selected project's scripts/ directory
Use project src/ methods: Import and use tested methods from the selected project's src/ modules
Save to project output: Place in the selected project's output/figures/
Reference properly: Use [@fig:name] in markdown — never \ref{}
Include data: Save both figures and data files

Customization

Adding New Sections

Create new markdown file in manuscript/
Add section label: {#sec:new_section}
Include cross-references to existing content
Add to the build pipeline (automatic)

Modifying Equations

Update equation content and labels
Update all references using [@eq:name]
Ensure label uniqueness across document

Extending Figures

Add new figure generation functions to existing scripts or create new ones
Import from projects/{name}/src/: Ensure scripts use projects/{name}/src/ methods for computation
Update scripts to generate new figures
Add figure references in markdown
Ensure proper file paths and naming

Adding New Source Code

Create modules in projects/{name}/src/ directory
Add tests in projects/{name}/tests/ directory (coverage requirements apply)
Update scripts to import and use new projects/{name}/src/ methods
Validate integration through the build pipeline

Troubleshooting

Common Issues

Missing references: Check that labels exist and are spelled correctly
Figure not found: Verify the figure and registry exist in the selected project's output/figures/
Equation numbering: Ensure unique labels across all files
Build failures: Check markdown validation output
Script import errors: Ensure projects/{name}/src/ modules exist and are properly tested

Reference Shows ??

Symptom: [@sec:label] shows ?? in PDF

Solution: Check label exists - search for {#sec:label_name} in manuscript files

Figure Path Error

Symptom: Figure renders but wrong location

Solution: Use relative path ../output/figures/name.png not absolute paths

Validation Errors

The validation system will report:

Missing image files
Unresolved cross-references
Duplicate equation labels
Bare URLs or non-informative links

Fixing Issues

Missing figures: Run appropriate generation scripts
Broken references: Check label spelling and existence
Validation errors: Address each reported issue
Build failures: Fix all validation issues before rebuilding
Import errors: Ensure projects/{name}/src/ modules meet coverage requirements

Architecture Compliance

Thin Orchestrator Pattern — File Structure

This template enforces the thin orchestrator pattern where:

projects/{name}/src/ contains ALL business logic, algorithms, and mathematical implementations
projects/{name}/scripts/ are lightweight wrappers that import and use projects/{name}/src/ methods
projects/{name}/tests/ ensures coverage of projects/{name}/src/ functionality
scripts/runner/execute_pipeline.py orchestrates the declared DAG pipeline

Script Requirements

Scripts in projects/{name}/scripts/ MUST:

Import methods from projects/{name}/src/ modules
Use projects/{name}/src/ methods for all computation
Handle only I/O, visualization, and orchestration
Include proper error handling for imports
Print output paths for render system
Set MPLBACKEND=Agg for headless operation

Scripts MUST NOT:

Implement mathematical algorithms
Duplicate business logic from projects/{name}/src/
Contain complex computations
Define new data structures

Summary

This template provides a framework for academic writing with:

Structured organization of content into logical sections
cross-referencing system for equations, figures, and sections
Automated figure generation with proper integration using projects/{name}/src/ methods
Validation system ensuring document integrity
Build pipeline generating both individual and combined PDFs
LaTeX export for further customization
Thin orchestrator pattern ensuring maintainability and testability

The system demonstrates best practices for academic writing while maintaining the flexibility to adapt to different research domains and writing styles, all while enforcing the architectural principles of the generic project template.

For more details on architecture and workflow, see:

../core/architecture.md - System design overview
../architecture/two-layer-architecture.md - two-layer architecture guide
../core/workflow.md - Development workflow

For manuscript formatting standards, see:

docs/rules/manuscript_style.md - manuscript formatting and style guide (equations, figures, tables, citations, lists, cross-references)

FilesExpand file tree

markdown-template-guide.md

Latest commit

History