MD Course - Repository maintenance

The public course content lives in docs/index.md and is published as a website. This README collects the technical maintenance notes for the repository.

Structure

• docs/ website (Jekyll).
• docs/index.md website index (the only content visible on the homepage).
• docs/episodes/ course episodes.
• docs/episodes/scripts/ episode source scripts.
• docs/episodes/notebooks/ renderable notebooks.
• docs/data/ sample data.
• docs/figures/ figures.
• scripts/ maintenance utilities.

Maintenance workflows

Makefile (targets)

Episode maintenance tasks can be run with make (or make all). All targets operate on the files under docs/episodes/ or their derived outputs.

• make / make all: run the full chain (sync-code, sync-notebooks, update-episode-toc, render-notebooks, check-links).
• make sync-code: sync the episode code blocks with the source scripts or notebooks.
• make sync-notebooks: sync scripts from notebooks and standardize notebook cell structure.
• make standardize-notebooks: only standardize notebook cell structure.
• make update-episode-toc: update the episode table of contents.
• make render-notebooks: render notebooks as HTML (docs/episodes/notebooks/rendered).
• make check-links: validate internal site links.
• make check-sync: verify notebooks match scripts.
• make check: run sync-code, sync-notebooks, render-notebooks, check-links, and check-sync.

Menu state (pre/course)

python scripts/set_stage.py pre
python scripts/set_stage.py course

Updates the block between <!-- stage:nav-start --> and <!-- stage:nav-end --> in docs/_layouts/default.html.

Sync embedded code blocks in episodes

python scripts/sync_episode_code_blocks.py

Updates the ```python blocks in markdown files under docs/ and replaces them with whichever script or notebook matches the same stem. If you need to force the source, add to the markdown:

<!-- sync-from: path/to/script.py -->

The script adds a link to the source file under the code block.

Sync scripts from notebooks

python scripts/sync_notebooks_from_scripts.py

Uses the notebooks in docs/episodes/notebooks/ as the source of truth and updates matching scripts in docs/episodes/scripts/. Respects cells separated with # %%.

Validate internal links

python scripts/check_links.py

Validates relative links inside docs/ and fails if any do not exist.

Verify figure assets

python scripts/check_figures.py

Walks the docs/ sources for /figures/ references, confirms the referenced files exist under docs/figures/, and flags any missing logos (with suggestions) or unused images. The command exits non-zero when figures are missing so you can detect the problem before deployment.

Generate a sample DCD

python scripts/generate_example_dcd.py

Generates a sample DCD under docs/data/ and requires an environment with OpenMM.

View the site locally (Jekyll)

This repository does not pin Jekyll versions, so the simplest option is using a globally installed Jekyll. If you prefer pinned versions, create a Gemfile and use bundle exec (out of scope for this README).

Install (Linux, Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y ruby-full build-essential zlib1g-dev
gem install jekyll bundler webrick

Install (macOS, Homebrew)

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
gem install jekyll bundler webrick

Run locally

jekyll serve --source docs --livereload --baseurl /Curso-MD-Analisis

The site will be available at http://127.0.0.1:4000/Curso-MD-Analisis/.

Common issues

• webrick not found (Ruby 3+): run gem install webrick.
• Port in use: use --port 4001 (or whatever port you want).
• Gem permission errors: install Ruby via rbenv or brew and avoid sudo gem.

Best practices

• Edit public content under docs/, not README.md.
• Avoid manually editing embedded code blocks in episodes: use the sync scripts to keep consistency.
• Keep links with {{ site.baseurl }} when pointing to resources under docs/.
• Log maintenance changes in this README as the repository evolves with new scripts or workflows.