Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
61 lines (50 loc) · 2.53 KB

CONTRIBUTING.md

File metadata and controls

61 lines (50 loc) · 2.53 KB

Contributing

Contributions are very welcome; please contact us by email or by filing an issue in our repository. All contributors must abide by our Code of Conduct.

Setup and Operation

  • Install uv.
  • Create a virtual environment: uv venv.
  • Activate it: source .venv/bin/activate.
  • Install dependencies: uv sync.
  • Run make on its own to see a list of common commands.

Style and Structure

  • Lessons are written in Markdown and compiled to HTML using the mccole static site generator.
    • Each lesson should take about an hour to work through.
  • Lessons are in slug directories
    • slug is short mnemonic
    • Each lesson must have an index.md file containing its content
    • And may also have a slides.md file with Shower slides
  • Use @/some/path/ for internal links
    • The leading @ is translated into a relative reference to the project root
  • The Markdown link definitions in _extras/links.md are appended to all Markdown files
    • This helps ensure consistent link URLs across pages
  • Figures, code inclusions, citations, and glossary references are formatted using mccole shortcodes.
  • The home page for the site is generated from README.md
    • The navigation menus for lessons and appendices are generated from the lessons and appendices div elements in README.md
  • Diagrams should be SVG files created with draw.io
  • bibliography/index.md has the bibliography as a definition list
    • Citation keys have IDs for linking
    • Use an inline HTML link b:key in files to create links
  • glossary/index.md has the glossary as definition list
    • Reference keys have IDs for linking
    • Use an inline HTML link g:key in files to create links
  • The _static directory contains CSS and JavaScript files
  • The _templates directory contains Jinja templates used to generate HTML

FAQ

Do you need help? : Yes—please see the issues in our repository.

What sort of feedback would be useful? : Everything is welcome, from pointing out mistakes to suggestions for better explanations.

Can I add a new section? : Possibly, but please reach out before doing so.

Why is this material free? : Because if we all give a little, we all get a lot.
⚡