This repository contains the site docs.uninett.no.
This website is built using Docusaurus 2.
Editing the site directly on GitHub is suitable for non-technical personell who wish to edit the site contents as easy as possible. This can be performed through simply visiting the page you wish to edit, and then clicking on the "Edit this page" / pencil symbol link visible in the bottom left of the page.
Another option is to browse the Sikt Docs file structure directly on GitHub, on GitHub you will be able to edit pages, upload images, create new pages and even create new folders which will represent a new Topic/subject if necessary.
Do note that in order for this new Subject/Topic to be visible on the landing page you will have to add it to the index. Some experience with React.js will be beneficial for this task. If you require help feel free to contact Platon. You can add a new SUbject/Topic-component inside of the file located in src>pages>index.js. It should look similar to this:
<Topic
title="mySubject"
link="docs/mySubject"
imageUrl="img/mySubjectImageIfAvailable.svg"
>
Write a short description about my subject here.
</Topic>
In order to edit this site locally you will have to clone the repository, commit your changes and initiate a pull request. For external contributors you may instead fork the repository and initiate a pull request from that fork.
Docusaurus uses Node.js, so you need to install that if you do not have it.
To start a development copy of the site, install the dependencies using npm ci
and start the web server
using npm run start
:
npm ci
npm run start
You can then access a live version of the site at http://localhost:3000/.
The dependency in use for offline searching only supports production builds. Hence you will see the search in the top right corner always displaying "Loading..." when running the development server.
If you wish to test the search function while developing you will need to make a production build first by running npm run build
then serving it regularly with npm run serve
:
npm run build
npm run serve
You can then access a live version of the site at http://localhost:3000/.
The master
-branch on this project is protected, so all changes need to go via pull requests.
Create a new branch using Git, e.g.:
git checkout -b my-branch-name
You can then commit your changes to that branch:
git add [my changed files]
git commit -m "insert your change message here"
And push the new branch:
git push -u origin my-branch-name
Once the branch is pushed, you can create a pull request for your new branch at github.com/sikt-no/docs/compare.
When you have created a new pull request, you should review the state of the pipeline for the pull request as well as verify the review copy of the site. Once you have verified that the changes are correct, merge the changes into the master branch.
Merging the changes into the master branch will update the production site at docs.uninett.no.
To prevent accidentally breaking the project due to unintended upgrades of dependencies, all versions used in this project are pinned.
There are three sets of dependencies that can be updated:
- The versions of Node packages.
- The versions of GitHub Actions.
- Docusaurus.
Dependabot will automatically check for updates to node modules monthly and GitHub Actions weekly. If an update is available, it will proceed to create a new branch, commit the change and submit a pull request to merge the dependency upgrades into master.
To update the versions of Node packages, we need to update package.json
and package-lock.json
.
Since we use pinned versions for consistency it might be necessary to manually inspect package.json
and change the versions to the newest version available through npm. After the change you may want to run npm install
to upgrade package-lock.json to reflect the changes.
You can also automatically update all the packages listed to the latest version with npm:
Warning: This will modify package.json and package-lock.json
npm update
Please proceed to inspect that the resulting build(s) work as expected before you decide to merge this upgrade into master.
Docusaurus 2 is still in beta, which means that they sometimes perform breaking changes. Some extra care should therefore be taken when updating Docusaurus.
The safest way to update Docusaurus is to create two directories with the old and new version of Docusaurus and then compare those two directories. This allows you to see what has changed between the versions in addition to the version numbers of the packages.
First install the version in use in packages.json
in the old
-directory:
$ mkdir -p /tmp/docusaurus-update/old
$ cd /tmp/docusaurus-update/old
$ npx [email protected] docs-sikt-no classic
[...]
Success! Created docs-sikt-no
Inside that directory, you can run several commands:
[...]
Happy hacking!
Then install the latest version in the new
-directory:
$ mkdir -p /tmp/docusaurus-update/new
$ cd /tmp/docusaurus-update/new
$ npx create-docusaurus@latest docs-sikt-no classic
[...]
Success! Created docs-sikt-no
Inside that directory, you can run several commands:
[...]
Happy hacking!
The two versions can then be compared using the diff
command:
$ cd /tmp/docusaurus-update
$ diff --recursive --unified --new-file --exclude=package-lock.json --exclude=node_modules --color=always old new | less -R
This will show all autogenerated files that were changed in this update. You can then manually apply those changes that are relevant to this repository.