Skip to content

Authoring

Jump to bottom
Drew Lewis edited this page Jul 12, 2024 · 4 revisions

Authoring

The project is set up to use GitHub Codespaces to supporting authoring within the web browser, or a locally installed VS Code application.

TIP: Use Chrome.

Our codespace is set up to allow the authoring of our web and print targets using the PreTeXt authoring toolkit described in the PreTeXt Guide.

General Workflow

  1. Create a new branch.
  2. Make your changes. Be sure to preview the output.
  3. Commit and pushyour changes.

Note: if you receive the error message Can't push refs to remote. Try running "Pull" first to integrate your changes., you forgot to create a new branch. See below about fixing branch issues.

  1. Create a pull request.

See here for detailed instructions with screenshots of how to do this in Codespaces.

Building exercise bank

Currently CheckIt is not set up to work with Codespaces, but the bank can still be built.

python scripts/bank/build.py

Deploying to the public

These steps should be followed from the main branch only to ensure only the accepted changes to the book are deployed to the public.

  1. build web target using PreTeXt
  2. build print target using PreTeXt
  3. build slides target using PreTeXt
  4. build worksheet target using PreTeXt
  5. Build bank using python scripts/bank/build.py
    • One liner: pretext build web && pretext build print && pretext build slides && pretext build worksheet && python scripts/bank/build.py
  6. deploy using PreTeXt
    • pretext deploy --preview can be used to stage what deployment will look like in output/stage and open a preview browser

Alternatively, all (non Checkit) pretext targets can be built using

for TARGET in $(xpath -q -e '//target[not(@name="checkit")]/@name' project.ptx | sed 's/name="//' | sed 's/"//'); do pretext build $TARGET; done

How to fix branch issues

If you accidentally make updates to the main branch, after pushing you will get the error message Can't push refs to remote. Try running "Pull" first to integrate your changes.

To fix this, open the Terminal and copy-paste the following lines into the Terminal to fix your Git history:

BRANCH=branchfix-`xxd -l3 -ps /dev/urandom`
git stash
git branch $BRANCH
git reset --hard origin/main
git checkout $BRANCH
git stash pop
Clone this wiki locally