This repository hosts to documents for the ICBO 2023 website. The website is built using mkdocs and the deployment of the website is controlled using the github action .github/workflows/build-deploy-documentation.yaml. The github action has been configured to run if any changes are made to mkdocs.yaml, files in the docs/ or docs/images/ directories, or after a pull request is merged. This allows to closely track the repository history using pull requests (if desired).
To make website available, you have to associate the repository with a github.io website (e.g., https://icbo-conference.github.io/icbo2023). The is done be clicking on the settings icon next to About:
and then setting the necessary information for Webpage:
The template is set up to use mkdocs to configure a github.io website. The deployment of the website is controlled using the GitHub action .github/workflows/build-deploy-documentation.yaml. The GitHub action has been configured to run if any changes are made to mkdocs.yaml, files in the docs/, docs/images/, docs/papers/, docs/slides/, or docs/flash-talks/ directories, or after a pull request is merged. Using pull requests allows you to closely track changes made to the repository (if desired). The icbo2023 conference repository is an example of how a repository can be configured using mkdocs.
The template provides a set of default webpages in the docs/ folder. These include:
call-for-submissions.md
co-organizers.md
contact-information.md
icbo-hotels.md
icbo-registration.md
icbo-schedule.md
icbo-travel.md
keynote-speakers.md
papers-and-poster-abstracts.md
proceeding-publication-requirements.md
program-committee.md
submit-jbms-icbo.md (optional)
workshops-and-tutorials.md
The content for the landing page is in the index.md file. You can add or remove content as needed (see below).
The website navigation menu is controlled by associating menu labels with markdown files in mkdocs.yml file.
The website content is contained in the docs/, docs/images/, docs/papers/, docs/slides/, and docs/flash-talks/ directories. Editing any of the *.md files or adding/changing an image should fire off an action to build and deploy the website. This GitHub action can be checked by navigating to the Actions page:
and verifying that the changes fired off an action. For example, here is an action that started as a result of an update the to the call-for-submissions.md:
After the action has finished running (it will have green check), verify that the edits are displayed on the website.
Adding new webpage takes two steps:
- Create the new
mdfile in thedocs/directory. - Edit the
navsection ofmkdocs.ymlto reference the new document and its title.
A new image is added to the website is done by simply saving a the image to the docs/images/ directory. However, referencing the image from the md file is a bit nuanced.
If you reference the image using markdown syntax, you include the images directory in the path to the images. For example, in the docs/call-for-submissions.md document, the reference to a image is done like so:
However, if you are customizing the image with an HTML <img> tag, you use the ../images directory in the path to the image. For example, src='../images/test-image.png' is the path needed when setting the margins of an image like this:
<img src='../images/test-image.png' align='left' style='margin:10px 20px 0px 0px' />
The reason for this has to do with how read the docs processes images, but I don't know the details of why.
If (for some reason) the GitHub action does not fire, you can manually run it. First, on the Actions page, select the Build and Deploy Static Mkdocs Documentation workflow.
Next, click on the Run workflow button.
Once the workflow starts running, you will see yellow dot beside the workflow name.
After the workflow, completes you will see a green check beside the workflow name.
Verify that the edits are displayed on the website.
.