About this Site

This site is maintained by Dr. Ben Franske, faculty member in the IHCC Information Technology Careers department, for the benefit of prospective, current, and alumni students in the department. This page explains how the site works and how to make updates to the site.

How the Site is Built

The site is comprised of static pages hosted on GitHub pages which are generated programmatically from AsciiDoc files using the Antora site generator. The complete source code for the site can be found in the itc-docs GitHub repository.

A GitHub workflow exists which automatically runs the Antora site generator and then deploys the site to GitHub pages each time a push to any YYYY.MM branch is made. The code for this workflow is also in the same repository.

How to Make Changes to the Site

If you do not have commit access to the itc-docs repository you will need to fork the repository on GitHub, download a copy, edit the files, upload to your forked repository, and then submit a pull request. It is strongly suggested that you setup the same Antora build workflow on your forked repository or run Antora locally to build and test your edits before submitting the pull request.

If you do have commit access to the itc-docs repository you can update your local copy, make changes, commit, and push to GitHub as you would with any normal source repository.

Update your local branch
git pull
Commit changes to all modified files with an short explanation of the changes
git add -A
git commit -m "a short explanation of what has been changed"
Upload changes to the remote repository (assuming you have commit permission there)
git push

Site Versioning

Antora is setup to automatically build multiple versions of the site based on the branches in Git that are identified by a branch name like YYYY.MM. The idea is that a new branch will be created from the main branch at the beginning of each semester in the YYYY.MM format. This branch will be used for changes made during that semester. At the end of the semester the changes will be merged back into the main branch. That way the final version of the site each semester will continue to be available as the latest commit of each branch. The YYYY.MM format was chosen as they will sort correctly to find the latest branch. For example at the beginning of Fall 2022 a branch 2022.08 will be created and at the beginning of Spring 2023 a branch 2023.01 will be created.

Create a branch at the beginning of the semester and switch to that branch
git pull
git checkout -b "YYYY.MM"
Upload changes to the new branch the first time by specifying it
git push --set-upstream origin YYYY.MM
At the end of the semester merge changes back into the main branch and upload it
git checkout main
git merge YYYY.MM
git push

Syntax for Site Content

As mentioned, the site uses AsciiDoc as the format for individual pages. The documentation for AsciiDoc is the first place to start if you want to know how to format something on a page. Because the site itself is built using the Antora program their documentation explains the heirarchy of directories and files, as well as some quirks to the AsciiDoc format specific to Antora.

Finding Source for a Page

The easiest way is to click the "Edit this Page" link in the upper right corner of any page. This will take you to an edit screen showing the page source and location. However, unless you have commit access to the repository you will need to fork the repository and submit a pull request as described above in order to make a change on the live site.

Antora organizes things into "components" which are parents to "modules". Each module can hold a number of pages, snippets (called partials), examples, images, and attachments. The idea is that the different components can be pulled from different Git repositories at build time and so can have different owners/permissions. Things can be linked or included between components and modules as needed.

For this site the major sections of the site, including a separate section for each faculty member that wants one (so they can be pulled from individual repositories), are their oen components. Most components are only using a "root" module at this time as there are a relatively limited number of pages in most components. The notable exception to this is that faculty components are likely to be divided into a module for each course so that various course pages, lab activities, images, attachments, etc. can be held together.

Site Design and Layout

The design and layout of the site is controlled by the UI bundle which is part of the Antora playbook.

Search Capability

A JavaScript based search capability has been added to the site using the Lunr module for Antora. This is included in the build process through the build workflow and enabled in the playbook.

Document Build Time: 2024-10-30 23:55:42 UTC
Page Version: 2024.01
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License