Mondo website editing guidelines¶
These instructions are for updating the Mondo Disease Ontology web site (https://mondo.monarchinitiative.org/). The files for the web site are contained within the
mondo repo and the web site files are in the
gh-pages branch. A GitHub Action called
pages build and deployment deploys the web site. The web site is built with Jekyll.
- Clone the Mondo GitHub repo locally
- Install Docker
Get the latest web site files locally. This can either be done in the Terminal or using GitHub Desktop.
Get the latest
gh-branches files from the remote GitHub repo¶
Using Git from the Terminal¶
- In the Terminal, navigate to your local directory, as:
- Checkout the branch that contains the web site files as:
git checkout gh-pages
- Get the latest updates for the branch from the remote as:
git pull(it is recommended to do a pull request from the gh-pages branch)
Using GitHub Desktop¶
- Change the "Current Branch" to
- Click "Fetch origin" to pull the latest updates for the branch from the remote.
Run the web site server locally¶
If you already have Jekyll installed locally, you can follow these legacy instructions. Otherwise, skip to the section "Run the web site locally using Docker".
bundle exec jekyll serve -l - this will allow you to view the website in real time, as you make edits.
2. The output should look like below:
Configuration file: /Users/vasilevs/git/mondo/_config.yml Source: /Users/vasilevs/git/mondo Destination: /Users/vasilevs/git/mondo/_site Incremental build: disabled. Enable with --incremental Generating... Invalid theme folder: _sass Remote Theme: Using theme mmistakes/minimal-mistakes Jekyll Feed: Generating feed for posts Pagination: Pagination is enabled, but I couldn't find an index.html page to use as the pagination template. Skipping pagination. GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data. done in 4.67 seconds. Auto-regeneration: enabled for '/Users/vasilevs/git/mondo' LiveReload address: http://127.0.0.1:35729 Server address: http://127.0.0.1:4000/mondo/ Server running... press ctrl-c to stop.
- Open the link http://127.0.0.1:4000/mondo/. Note: you can right click on the URL and open URL
- Make your changes to the website files.
- Control+C to end the session
- Commit changes to GitHub (example when working on Terminal):
git add -A;git commit -m "update webpage";git push
NOTE: Since the web site is maintained on a branch, when changes are pushed to the remote this automatically triggers a GitHub Action to deploy the branch. There is no Pull Review step.
Run the web site locally using Docker¶
Navigate to the mondo directory, e.g.
Confirm you are in the
gh-pagesbranch and you have pulled the latest changes locally.
Run the web site server locally as:
docker run --name mondo-docs -p "4000:4000" -p "35729:35729" --volume="$(pwd):/srv/jekyll:Z" -it jekyll/jekyll bash
(this will put you in a ternminal inside the Docker container in the working directory)
NOTE: If using an Apple processor (e.g. M1/M2), try running the command as below to avoid warning messages:
docker run --platform linux/amd64 --name mondo-docs -p "4000:4000" -p "35729:35729" --volume="$(pwd):/srv/jekyll:Z" -it jekyll/jekyll bash
Once the Container is running, you can use common Linux commands to navigate the file hierarchy, e.g.
lsshould show you the Mondo doc files
jekyll serve -lto have a continuous build so that the local web site shows changes without having to refresh your browser (live reload).
jekyll buildif you want a one time build
Open your browser to:
Try to edit a doc file and you'll see the build update happening in the terminal. Once you see something like
...done in 3.704351825 seconds.in the terminal, the browser should refresh automatically.
To exit from the
jekyll servemode, use
exitin the Terminal to exit the Docker container.
This will cause Docker to stop/exit the container but the container is still available for a later quicker start (as opposed to the initial startup with the docker run ... above).
- If you want to do another editing session later, and you've already done the above
docker run ....steps earlier, you can use
docker start -ai mondo-docsto get back into the already setup container and then run the Jekyll commands above (Step 5), or run anything else you can see here
If you're all done with editing and do not want to keep the Docker container around, you can run
docker rm mondo-docs. After doing this, you'll need to start from
docker run ...(Step 3) next time.
Commit your edits to the
gh-pagesbranch either using the Terminal or GitHub Desktop.
- Push your local changes to the remote. NOTE: Since the web site is maintained on a branch, when changes are pushed to the remote this automatically triggers a GitHub Action to deploy the branch. There is no Pull Review step.