markdown-template-guide.md

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 a academic paper structure with the following markdown files:

Core Sections

1. manuscript/preamble.md - LaTeX preamble with styling and packages
2. manuscript/01_abstract.md - Research overview and key contributions
3. manuscript/02_introduction.md - Introduction with section references and overview
4. manuscript/03_methodology.md - Mathematical framework with numbered equations
5. manuscript/04_experimental_results.md - Results with figure and equation references
6. manuscript/05_discussion.md - Discussion with cross-references to previous sections
7. manuscript/06_conclusion.md - Conclusion summarizing all contributions
8. manuscript/98_symbols_glossary.md - Auto-generated API reference from projects/{name}/src/

Cross-Referencing System

Section References

Use \ref{sec:section_name} to reference sections:

# Introduction {#sec:introduction}

The methodology described in Section \ref{sec:methodology} shows...

Available section labels:

• {#sec:introduction} - Introduction
• {#sec:methodology} - Methodology
• {#sec:experimental_results} - Experimental Results
• {#sec:discussion} - Discussion
• {#sec:conclusion} - Conclusion

Equation References

Use \eqref{eq:equation_name} to reference equations:

\begin{equation}\label{eq:convergence}
\|x_k - x^*\| \leq C \rho^k
\end{equation}

The convergence rate \eqref{eq:convergence} shows...

Key equations in the template:

• eq:objective - Main objective function
• eq:optimization - Optimization problem
• eq:update - Algorithm update rule
• eq:convergence - Convergence bound
• eq:adaptive_step - Adaptive step size
• eq:memory - Memory scaling
• eq:accuracy - Accuracy metric
• eq:advantage_metric - Performance advantage
• eq:robustness_metric - Robustness measure
• eq:complexity_bound - Complexity bound
• eq:final_improvement - Overall improvement

Figure References

Use \ref{fig:figure_name} to reference figures:

\begin{figure}[h]
\centering
\includegraphics[width=0.8\textwidth]{../output/figures/experimental_setup.png}
\caption{Experimental setup diagram}
\label{fig:experimental_setup}
\end{figure}

Figure \ref{fig:experimental_setup} shows the pipeline...

Available figures:

• fig:example_figure - Basic example function plot
• fig:convergence_plot - Algorithm convergence comparison
• fig:experimental_setup - Experimental pipeline diagram
• fig:scalability_analysis - Performance scaling analysis
• fig:ablation_study - Component ablation results
• fig:hyperparameter_sensitivity - Parameter sensitivity surface

Table References

Use \ref{tab:table_name} to reference tables:

| Metric | Value | Unit |
|--------|-------|------|
| Performance | 23.7% | improvement |

Table \ref{tab:performance_summary} shows...

LaTeX Features Demonstrated

Equation Environments

The template shows proper use of LaTeX equation environments:

\begin{equation}\label{eq:example}
f(x) = \sum_{i=1}^{n} w_i \phi_i(x)
\end{equation}

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: Section \ref{sec:methodology}
- Equation references: \eqref{eq:convergence}
- Figure references: Figure \ref{fig:convergence_plot}
- Multiple references: equations \eqref{eq:objective} through \eqref{eq:convergence}

Figure Generation

Scripts

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

1. example_figure.py - Basic example figure using projects/{name}/src/ methods
2. generate_research_figures.py - research figures using projects/{name}/src/ methods

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:

# Import projects/{name}/src/ methods for computation
from project.src.example import add_numbers, calculate_average

def generate_figure():
    # Use projects/{name}/src/ methods for all computation
    data = [1, 2, 3, 4, 5]
    avg = calculate_average(data)  # From projects/{name}/src/example.py
    
    # Script handles visualization and output
    fig, ax = plt.subplots()
    ax.plot(data)
    ax.set_title(f"Average: {avg}")
    return fig

Output Structure

Figures are automatically saved to:

• output/figures/ - PNG files
• output/data/ - NPZ and CSV data files

Integration

Figures are referenced in markdown using relative paths:

\begin{figure}[h]
\centering
\includegraphics[width=0.8\textwidth]{../output/figures/figure_name.png}
\caption{Figure caption}
\label{fig:figure_name}
\end{figure}

Validation System

Manuscript Validation

Markdown validation is performed via the infrastructure validation module:

uv run python -m infrastructure.validation.cli markdown projects/{name}/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/code_project/src/ projects/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 (scripts/execute_pipeline.py):

1. Runs tests with coverage requirements (90% project, 60% infra)
2. Executes scripts to generate figures and data (validating projects/{name}/src/ integration)
3. Validates manuscript for references and images
4. Builds individual PDFs for each manuscript file
5. Creates combined PDF with all sections
6. Exports LaTeX source files

Output Files

Generated outputs include:

• Individual PDFs for each section
• Combined PDF with all sections
• LaTeX source files
• Figures and data files
• Coverage reports

Best Practices

Writing New Sections

1. Add section label: # Section Title {#sec:section_name}
2. Use descriptive equation labels: \label{eq:descriptive_name}
3. Reference previous content: Use \ref{} and \eqref{}
4. Include figures: Reference generated figures with \ref{fig:name}

Adding Equations

1. Use equation environment: \begin{equation}\label{eq:name}...\end{equation}
2. Choose descriptive labels: Avoid generic names like eq:1
3. Reference consistently: Use \eqref{eq:name} throughout

Creating Figures

1. Generate with scripts: Use scripts in projects/{name}/scripts/ directory
2. Use projects/{name}/src/ methods: Import and use tested methods from projects/{name}/src/ modules
3. Save to output: Place in output/figures/
4. Reference properly: Use \ref{fig:name} in markdown
5. Include data: Save both figures and data files

Customization

Adding New Sections

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

Modifying Equations

1. Update equation content and labels
2. Update all references using \eqref{}
3. Ensure label uniqueness across document

Extending Figures

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

Adding New Source Code

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

Troubleshooting

Common Issues

1. Missing references: Check that labels exist and are spelled correctly
2. Figure not found: Verify figure file exists in output/figures/
3. Equation numbering: Ensure unique labels across all files
4. Build failures: Check markdown validation output
5. Script import errors: Ensure projects/{name}/src/ modules exist and are properly tested

Reference Shows ??

Symptom: \ref{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

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

Architecture Compliance

Thin Orchestrator Pattern

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/execute_pipeline.py orchestrates the entire 10-stage 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)