How to update the larsoft.github.io wiki pages

Notice that the LArSoft wiki pages are in the wiki subdirectory. The top level of the repository is reserved for the index and these instructions about updating the pages.

If you want to modify or create a new page, please open a pull request. Members of the documentation group and patch release managers are able to edit these pages directly.

For other requests, comments, or questions, please create a redmine issue or contact the SciSoft team.

Notes about formatting

Be aware that there are some differences in allowed syntax between Jekyll pages and basic github markdown.

Notice that lines will concatenate unless you put a blank line before any line that should start its own “paragraph”.

Bare links will not display properly on the Jekyll pages.

at https://github.com/LArSoft/larsoft.github.io/wiki

Instead use the []() format

[LArsoft github.io repository](https://github.com/LArSoft/larsoft.github.io/wiki)

All links should be https. Please do not embed email addresses. We will be using subdirectories within the wiki directory to make support and navigation easier.

It is possible to add a Table of Contents. This will be placed at the top of the page, BEFORE the page contents. See this commit to the Breaking Changes page for an example. An explanation is here. Note that the table of contents will not show up in a preview, it will be generated when the page is rendered for display.

We are currently using the Jekyll “minimal” theme. This theme allows us to use certain style commands for extended functionality. The style commands do not work in all themes.

For people with direct edit access

For small changes, we recommend editing the wiki pages in place in the LArsoft github.io repository

Editing the files in place allows you to use the preview option.

Once you commit a change, it can take up to 20 minutes before the change is active on the LArSoft Jekyll pages

You will find the upload status in the bottom right corner of LArSoft github.io
The status does not change in real time, you need to refresh the page.
Possible status types are active, pending, in progress, and failure.
Note that if the status is “active”, that may be for a previous update. You can check by clicking on “github-pages” next to the status report.
If the upload has failed investigate the failure by clicking on “github-pages” next to the status report.

About the site map

The initial version of the sitemap was generated by hand using the find command.

git clone git@github.com:LArSoft/larsoft.github.io.git
find larsoft.github.io -name "*.md" > larsoft.github.io/new_sitemap.txt

edit the file to add https:// in front of larsoft.github.io and remove the trailing .md from each entry.

diff new_sitemap.txt sitemap.txt

The changes should be minimal - a new or removed line. If not, edit new_sitemap.txt to fix any problems. Once you are happy:

mv new_sitemap.txt sitemap.txt
commit -m"some useful message" sitemap.txt
git push origin main