MTEX website

The source of https://mtex-toolbox.github.io, a Jekyll site built on the Documentation Theme for Jekyll. GitHub Pages serves the master branch of mtex-toolbox/mtex-toolbox.github.io and builds it on every push.

Most pages are generated by MATLAB from the MTEX sources (see Rebuilding the documentation). CLAUDE.md has the detailed notes on the build.

The site checkout sits beside the MTEX checkout and the makeDoc/ toolbox in one working folder:

mtex/
├── master/       MTEX, the branch the documentation follows
├── makeDoc/      the DocHelp publishing toolbox
└── web/          this repository, master
    └── figures/  clone of mtex-toolbox/figures

Setting up

From the working folder that holds the MTEX checkout master/:

git clone git@github.com:mtex-toolbox/mtex-toolbox.github.io.git web
git clone git@github.com:mtex-toolbox/figures.git web/figures
cd web
bundle config set --local path ~/.local/share/gem/bundle   # if the system gem directory is not writable
bundle install

Looking at the site locally

bundle exec jekyll serve

It serves at http://127.0.0.1:4000.

Rebuilding the documentation

Inside MATLAB, from the matlab/ folder of the site checkout. Start MATLAB in the MTEX checkout master/, so that startup_mtex puts its sources on the path.

makeDoc                          % everything: function reference, documentation, examples
makeDoc('doc')                   % only the documentation pages
makeDoc('file','EBSDTutorial')   % one page
makeDoc('checkLinks')            % dead-link scan

The figures go to ../figures, the figures clone. CLAUDE.md lists all options and explains the image diff and the revert pass.

Deploying

From web/, on master:

./update.sh --dry-run   # show what would be committed
./update.sh             # publish figures, then commit and push the pages
./update.sh --all       # take every change, not only what a build writes

update.sh first publishes changed figures through tools/deploy-figures.sh, then stages only what a build writes (pages, images, _data/sidebars, search.json), shows it, asks, commits and pushes master. GitHub Pages rebuilds the site within a few minutes. The script refuses to run on any branch other than master.

To publish figures alone:

tools/deploy-figures.sh --dry-run
tools/deploy-figures.sh

The figures repository keeps a single commit: every deploy replaces it and force-pushes.