Editing the Mizer Website

Website built from package documentation

The mizer website at https://sizespectrum.org/mizer/ is created programmatically from the documentation included in the mizer GitHub repository. Thus to edit the website just means editing this documentation. The website creation is performed by the pkgdown package. You can trigger a build in your local repository by issuing the commands

pkgdown::build_site()

This will convert all existing documentation into html files and put these into the docs subdirectory of your mizer directory. In detail:

1. All .Rmd files in the vignettes subdirectory (and its subdirectories, if any) will produce html files of the same name in docs/articles.

2. All .Rd documentation files in man will produce html files of the same name in docs/reference.

3. The NEWS file will be converted to docs/news/index.html

4. The README.md file will be converted to docs/index.html.

Then the package will use the information in the _pkgdown.yml file to create a navbar and index pages. The navbar is configured with

navbar:
  title: "mizer"
  left:
    - icon: fa-home fa-lg
      href: index.html
    - text: "Get Started"
      href: articles/mizer.html
    - text: "Articles"
      href: articles/index.html
    - text: "Reference"
      href: reference/index.html
    - text: "Publications"
      href: articles/publications.html
    - text: "News"
      href: news/index.html
  right:
    - icon: fa-github fa-lg
      href: https://github.com/sizespectrum/mizer

This is quite self-explanatory, specifying the order of the navbar entries, their text and link destination, and whether they are on the left or right side. It is clearly easy to add additional navbar entries. It would be possible to also include drop-down items in navbar. See the pkgdown documentation for more details.

The file docs/articles/index.html is created according to the article: section in the _pkgdown_yml file. At an early stage it looked as follows:

articles:
- title: User Guides
  contents:
  - model_description
- title: Developer Guides
  contents:
  - developer_vignette
  - mathematical_details

By now it has more entries to link to more vignettes. It is not necessary to use this index file. The menu entry could just as well point to a more elaborate file created from an .Rmd file in the vignette subdirectory, which might become useful in the future.

The file docs/reference/index.html is created according to the reference: section in the _pkgdown_yml file, with a similar syntax as the article: section.

Changing page content

At the top of every page on the website, except the homepage, there is a link to the page source. So it is easy to know which file to edit to make changes to a page. If you want to rebuild the website after making a change to a single page you may not want to re-build everything. You can rebuild just a single vignette. For example to rebuild this page after editing the vignette vignette/editing_website.Rmd you can call

pkgdown::build_article("editing_website")

To rebuild the reference pages after changing the roxygen code doc you can run

pkgdown::build_reference()

To change the homepage you edit index.md. This file is very similar to README.md that is used on the mizer homepage on GitHub, but can contain extra content like embedded videos that the GitHub homepage does not support. After changes to index.md you can update your local copy of the website with

pkgdown::build_home()

Of course these changes will affect only your local copy of the website. To get those changes reflected on the online site you will need to make a pull request for your changed files against the master branch of the upstream repository.

Sync navbar to mizerCourse

When the navbar has been changed, to get the same changes into the navbar on the mizer course run the script in dev_scripts/sync_course_navbar.

Maintaining the AI documentation files

The docs/ directory contains two files intended for AI agents (such as Claude or ChatGPT) that help users work with mizer:

• docs/llms.txt — a navigation index following the llms.txt convention: a brief package overview followed by a categorised list of all exported functions with links to their .md reference pages.
• docs/llms-full.txt — an extended version that inlines the full documentation of the most important reference pages and key articles, so an agent can answer most questions without fetching individual pages.

After running pkgdown::build_site()

pkgdown 2.2.0 auto-generates docs/llms.txt from the package index. The auto-generated version starts with noisy image and badge markdown. The committed version has an improved header (lines 1–23) that follows the llms.txt spec properly. After every site build you must restore that header:

1. Note where # Package index begins in the freshly generated file.
2. Delete everything above that line.
3. Paste the following at the top of the file (preserving the blank line before # Package index):

# Mizer

> An R package for dynamic multi-species size-spectrum modelling of fish communities.

Mizer models marine ecosystems subject to fishing. It tracks the full size distribution of each species and the plankton resource, computing growth, predation, and mortality rates from individual-level physiology and feeding interactions. A model is set up from a species parameter data frame, calibrated to a steady state matching observations, then projected forward under different fishing strategies.

## Installation

```r
install.packages("mizer")
remotes::install_github("sizespectrum/mizer")  # development version

Quick start

library(mizer)
params <- newMultispeciesParams(NS_species_params, NS_interaction)
sim <- project(params, t_max = 10, effort = 0)
plot(sim)

See the Get started article for a full walkthrough. Extension packages add new biology (temperature dependence, starvation mortality, seasonal dynamics) — see Using extension packages.

### Regenerating `llms-full.txt`

`docs/llms-full.txt` is **not** auto-generated by pkgdown — it is assembled
by a Python script that combines the `llms.txt` index with the inlined
content of the most important reference pages and articles.  Regenerate it
whenever the documentation changes substantially (new functions, revised
vignettes, etc.):

```python
import re, os

docs = 'docs'  # run from the mizer repo root

def read(path):
    with open(path) as f: return f.read()

def strip_images(text):
    return '\n'.join(l for l in text.split('\n') if not re.match(r'^\s*!\[', l))

def strip_references(text):
    m = re.search(r'\n## References\n', text)
    return text[:m.start()] if m else text

def process_ref(name):
    return strip_images(read(os.path.join(docs, 'reference', name))).rstrip()

def process_article(name):
    t = read(os.path.join(docs, 'articles', name))
    return strip_references(strip_images(t)).rstrip()

ref_pages = [
    'MizerParams-class.md', 'MizerSim-class.md', 'species_params.md',
    'newMultispeciesParams.md', 'project.md', 'steady.md', 'setFishing.md',
    'setResource.md', 'setBevertonHolt.md', 'getRates.md', 'matchGrowth.md',
]
articles = [
    'model_description.md', 'extending-mizer.md',
    'cheatsheet-analysis-and-plotting.md',
]

parts = [read(os.path.join(docs, 'llms.txt')).rstrip()]
parts.append('\n\n---\n\n# Full Reference Documentation\n\nThe sections below contain the complete documentation for the most important functions and articles. They are included here so that an AI agent can answer questions about mizer without fetching individual pages.\n')
parts.append('\n## Reference pages\n')
for name in ref_pages:
    parts.append('\n---\n\n' + process_ref(name) + '\n')
parts.append('\n## Key articles\n')
for name in articles:
    parts.append('\n---\n\n' + process_article(name) + '\n')

with open(os.path.join(docs, 'llms-full.txt'), 'w') as f:
    f.write('\n'.join(parts))

Save this script (e.g. as dev_scripts/build_llms_full.py) and run it from the repo root with python3 dev_scripts/build_llms_full.py after each site build.

To add or remove pages from llms-full.txt, edit the ref_pages and articles lists in the script.

GitHub pages

The website is hosted with GitHub Pages. In the settings pages of the mizer repository on GitHub the source is set to "master branch/docs folder". This means that only the master branch controls the website.

Search bar

The search bar on the website is powered by Docsearch from Algolia. This is a free service for open-source projects. The set-up is explained in the pkgdown documentation.

Embedding videos

It is easy to embed videos into a webpage by putting an iframe into the R Markdown source file. For example

<iframe width="560" height="315" src="https://www.youtube.com/embed/0RlXqLbFbWc" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

The GitHub site itself (as opposed to GitHub Pages) does not support embedded videos.