pretextbook.org

This will become the repository for the home page for PreTeXt, to be hosted at pretextbook.org.

Current status

The files to build the PreTeXt website live in the site directory. We hold on to a copy of old_site to help with the transition; eventually this will go away.

Inside site, the pages directory contains the markdown files that make up the content of the site, while the theme directory contains the templates and static resources (css, js, images, etc) used to style the site. The site.json file contains the build configuration for Pelican to generate the static html pages.

In scripts we include a build.sh bash script that can automate a local build of the Guide and all the various examples. These should be placed in subdirectories of the local output folder.

Then to generate the front pages, run pretext deploy --stage-only. This will create the static html pages in output/stage, copying the contents of each project inside output. (The location of these, and their destinations inside the stage directory is determined by the project.ptx file).

Finally, the contents of output/stage can be either deployed to a github pages or copied to another web server.

Future build process

It would be simple to use the fetch_sources.py script to download the most recent versions of the PreTeXt-generated parts of this site into a non-tracked source directory. Then the PreTeXt CLI could build each of these (using pretext build --deploys) into the appropriate subdirectory of output.

If we transition to this workflow, the following description would apply (but for now, we stick with the old way of building).

The PreTeXt-CLI allows for multiple targets to be built and to create a custom landing page using Pelican to generate the static landing pages. The static landing pages live in the site directory, which contains theme and pages directories, as well as a site.ptx file that specifies the build configurations for Pelican. Pelican will transform the .md files in pages, using the templates in theme and place the resulting static html in output/stage as part of the pretext deploy command.

The pretext deploy command will also copy the output from each target listed in project.ptx to its specified deploy-dir inside output-stage. Then this is all copied to the gh-pages branch which is pushed to github.

In addition to the static pages describing PreTeXt, the website contains many HTML and PDF documents generated by PreTeXt. These are created in two different ways.

1. The CLI builds them as targets listed in project.ptx. Before this is done, the most recent versions of these documents are downloaded from their respective repositories and placed in appropriate folders inside source, using the scripts/fetch_sources.py python script.
2. pretext/pretext builds them as specified in scripts/build.sh, placing them inside an appropriate static resources folder inside site. (TODO)

GitHub actions

All of the above process could be automated using github actions.

TODO:

• If we want to use the CLI to use the most recent commits from PreTeXt, we could easily clone the pretext repository and CLI repository and initialize the dev environment with poetry to complete the build. This can be part of a github action. (Perhaps this is done by default but can be overriden if there are errors?)