Github Pages setup

[StoneCypher]

It's site update time.

You can see the site changes here before you decide.

• Add a theme
• Extend some bullet points for details
• Add links where sensible
• Added one sub-header for clarity
• Fixed some markdown technicalities that were putting text into lists which wasn't meant to be there
• Improved the issues instructions page; added a screenshot
• Maintenance instructions

Too long, didn't read

npm -v

If that says something tool looking, you're good. If not, install node js.

Then, after merging,

cd ~/projects/reactor
git fetch --all && git pull
npm install
npm build

To update at any time,

npm build
git add . -A && git commit -m "what my updates were" && git push origin

Ok I'm reading now

This is a github pages setup. It relies on https://nodejs.org/en/ for update scripts, because that's more portable and less inscrutable than shell scripts on average.

I don't know you (I don't even know which transatomic person(s) I'm talking to) and I don't know if you're git/github sophisticated, so, instructions follow below. If this is something you already know, I apologize, and do not mean to be condescending.

What is this

Github Pages is free webhosting by Github. In the git tradition, it can work too many ways, and it's best to have some neckbeard just make choices. This PR represents such an effort.

Things in GH pages will be hosted at https://(orgname).github.io/(reponame)/. Note that it is .io, not .com.

The source of GH pages may be one of two things: the root /docs/ folder, or an alternate reality branch dedicated to the site. The latter choice is:

1. More powerful
2. Unnecessary
3. Wildly hard to maintain in practice

Since you aren't using /docs/, ... now you are. Your website lives there.

How is it built

Simply. This is a node.js standard package file using package.json scripts for automation. It relies on exactly one external package - rimraf - a dead package with a simple premise that is unchanged for years.

There are three steps. The first two are a single step together in package. The machine will do this all for you.

1. Nuke docs/
2. Remake the docs/ directory tree
3. Re-copy all markdown and the github pages config back into docs

As a result of step #3, if you change the theme in your GH pages config, it'll change itself back to my initial choice. Instructions in fixing that are below.

Why does the nerd keep saying build product

It is important to understand that the /docs/ folder is a build product. No changes ever belong there. It will get carpet bombed and remade by robots. Leave it the hell alone. Do your changes the way you were already doing them.

When you're done, just type npm build and wait a few seconds.

Commit the results and wait another 2 minutes. Your site will update when it's good and ready, the lazy slob.

I merged this and nothing happened

Yeah. You have to turn GH pages on first. It's easy.

I screenshotted my way through turning it on for myself on the fork. Yours will probably be at https://transatomic.github.com/reactor/, though I'm not 100% confident of that because orgs can do silly things.

---

1. Go to your repo. Go to the repo's settings tab (there's nine million settings tabs for everything in GH. good luck, adventurer)

---

2. It should look this-esque

---

3. Scroll to the middle. Find the section "data services." Turn on "vulnerability alerts." This just tells GH's robots "warn them if you see something bad." It's unlikely to ever matter for a document repo.

---

4. Scroll most of the way down and find the GH pages section.

---

5. Change it to say "master branch /docs/ folder." Hit save.

---

6. It will reload. Scroll down again, because programmers made this. You should see a URL that says where your new page will be. It takes several minutes for this to work, so if you try to go there immediately, lol, 404.

---

7. Initially it will look like this. (Actually it might be on the theme cayman by default from inheriting my testing. I'm not sure and I kind of don't care.)

---

8. I set it to the first theme. Afterwards it looked like this instead.

---

9. If you want to update the theme, because it's maintained in the code, there is an additional inobvious step.

1. First update the theme like you'd expect. Notice that it works. Ha! This is software. It will fail later when you don't expect it and don't remember the relevant context.
2. Later, you update the docs and rebuild. Wtf? The. The old theme is back?
3. That's because of a step at the end in package.json that copies its copy of the gh pages theme over the existing one
4. That's because nuking the docs folder nukes the gh pages config
5. So if you want to change the theme:
   • Make the change
   • Pull the repo. Notice GH has changed /docs/_config.yml
   • Replace the repo's githubpages_config.yml with that
   • Now the build process enforces your new theme instead of the old one