McCole

A template for Ark-based tutorials.

1. Set up Python environment:

   1. Create lib/mccole/.
   2. Create lib/mccole/requirements.txt.
   3. Add ark and pymdown-extensions to lib/mccole/requirements.txt.
   4. Create requirements.txt with -r lib/mccole/requirements.txt.
   5. Create conda environment mccole.
   6. Install packages with pip install -r requirements.txt.

2. Set up minimal Ark site:

   1. Create config.py.
   2. Define title, repo, and author.
   3. Define theme to be mccole.
   4. Define src_dir to be src.
   5. Define out_dir to be docs.
   6. Define extension to be /.
   7. Enable Markdown extensions.
   8. Create empty src/index.md.
   9. Create lib/mccole/templates/node.ibis template with nothing but {{node.html}}.

3. Create license and code of conduct pages:

   1. Create LICENSE.md and CODE_OF_CONDUCT.md for GitHub to display.
   2. Create src/license/index.md and src/conduct/index.md to generate pages in docs.
   3. Define rootfile shortcode in lib/mccole/extensions/rootfile.py to include files from the root.
   4. Create lib/mccole/extensions/util.py to hold utilities.
   5. Add __pycache__ to .gitignore to stop util.pyc from being included in Git.

4. Create glossary.

   1. Add src/glossary/index.md with [% glossary %] shortcode.
   2. Add [%g ssg "text" %] to src/index.md as test case.
   3. Create info/glossary.yml with Glosario-format glossary.
   4. Add lang="en" to config.py to specify language.
   5. Create lib/mccole/extensions/glossary.py with implementation of glossary and g shortcodes.
   6. Add test case for g shortcode to src/index.md.
   7. Add markdownify function to lib/mccole/extensions/util.py for Markdown conversion.

5. Automation.

   1. Create Makefile that includes lib/mccole/mccole.mk.
   2. Create lib/mccole/mccole.mk with targets to rebuild and check.
   3. Add ruff to lib/mccole/requirements.txt and install it.

6. Styling pages.

   1. Create lib/mccole/resources/mccole.css with beginnings of (unresponsive) styling.
   2. Add HTML layout to lib/mccole/templates/node.ibis.
   3. Add head.html and foot.html to lib/mccole/templates directory.
   4. Add lib/mccole/resources/logo.svg for use as favicon.
   5. Add .nojekyll file to prevent GitHub from re-rendering pages.

7. Add front matter to index.md pages with titles.

8. Add cross-referencing and table of contents.

   1. Add chapters and appendices to config.py to define order.
   2. Add _number_contents and _collect_titles to lib/mccole/extensions/init.py to gather information.
   3. Create lib/mccole/extensions/toc.py for cross-references and table of contents.
   4. Add x shortcode to cross-reference chapters and appendices.
   5. Add toc shortcode to create table of contents.
   6. Add src/intro/index.md and src/finale/index.md as test cases.

9. Add bibliography.

   1. Modify lib/mccole/requirements.txt to install pybtex package.
   2. Add info/bibliography.bib (BibTeX-formatted bibliography).
   3. Add lib/mccole/bin/make_bibliography.py to translate BibTeX into HTML in tmp/bibliography.html.
   4. Modify lib/mccole/mccole.mk to build HTML version of bibliography.
   5. Modify lib/mccole/resources/mccole.mk to display bibliography.
   6. Add bibliography shortcode to include bibliography in page.
   7. Add b shortcode to reference bibliography entries.
   8. Add src/bib/index.md to show bibliography.
   9. Modify config.py to include bib as appendix.

10. Add figures and tables.

    1. Add lib/mccole/extensions/figure.py with shortcode f and figure inclusion figure.
    2. Add lib/mccole/extensions/table.py with shortcode t and figure inclusion table.
    3. Rename lib/mccole/extensions/init.py to lib/mccole/extensions/batch.py to reflect purpose.
    4. Add startup task in lib/mccole/extensions/batch.py to find and number all figures and tables.
    5. Add copy field to config.py with globs of files to copy directly (just *.svg for now).
    6. Add finalization code to lib/mccole/extensions/batch.py to copy files.
    7. Add examples of figures and tables (and references) to src/intro/index.md and src/finale/index.md.
    8. Move localization into lib/mccole/extensions/util.py.

11. Add navigation links and a proper title.

    1. Collect all metadata in lib/mccole/extensions/batch.py.
    2. Add lib/mccole/templates/title.html to format title and prev/next navigation links.
    3. Include title.html in lib/mccole/templates/node.ibis.
    4. Add lib/mccole/extensions/filters.py with various filters required by template additions.
    5. Add flex grid to lib/mccole/resources/mccole.css.
    6. Modify src/license/index.md and src/conduct/index.md to strip inherited title of root pages.