Updating and Changing the Wiki

There are two main ways to edit the wiki. The first option is much easier—asking AdComm for an edit—but will likely be slower and you may not have as much control over the exact language as you would like. The second option is to directly edit the wiki yourself. This will require some level of technological know-how, but in this article we’re going to do our best to explain how to make these edits yourself in great detail.

Asking AdComm for an Edit

You can request an edit from Admin Committee in a few ways—the preferred method is by asking for an edit with the exact language you would prefer in the AdComm wiki thread on the TDSA Discord server. If you do not have access to the Discord server for whatever reason, you can email the chapter at ncpdsa@gmail.com to request an edit.

Directly Editing the Wiki

This part is going to get quite technical, quite fast. If you need any help with troubleshooting, feel free to ask in the AdComm wiki thread on the TDSA Discord server or feel free to DM me for help (@yeti_ on Discord).

Also contact AdComm for the location of the Wiki git repository.

Getting Started

Windows Setup

Before you begin editing the wiki from your own device, you will need to download a couple things. The following programs are heavily suggested if you are using a Windows device: git-bash, Visual Studio Code, and mdBook (click the option for windows-msvc).

Linux Setup

Debian and its derivatives (Ubuntu, Knoppix, Kali, etc.)

sudo apt install -y vim git rust-all rustup
rustup default stable
curl -LsSf https://astral.sh/uv/install.sh | sh
cargo install --locked mdbook@0.4.52 mdbook-mermaid@0.15.0 mdbook-glossary@0.3.0
# Clone your git repository
# git submodule update --init --recursive --remote
vi ~/.bashrc
# Add a line at the end that says 
export PATH="$HOME/.cargo/bin:$PATH"
# And save the file. :wq
source ~/.bashrc
uv run --directory ./glossary-builder/ main.py $PWD/glossary.csv $PWD/glossary.yml

RedHat

RedHat, owned by IBM, is on the Boycott, Divestment, and Sanctions (BDS) list, and instructions will not be provided here.

Macintosh Setup

On a Mac, the easiest way to install the needed software is by using the brew package manager. If you don’t have brew installed, run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

in a terminal window to install it.

You can use any editor you would like, but Visual Studio is a popular choice. nano is preinstalled, and vim can be installed with brew install vim.

Then, to install the needed software, run:

brew install git rust uv
cargo install --locked mdbook@0.4.52 mdbook-mermaid@0.15.0 mdbook-glossary@0.3.0
# After checking out the repository
uv run --directory ./glossary-builder/ main.py $PWD/glossary.csv $PWD/glossary.yml

You should then have everything you need.

Best Practices

Important notes

• To update Mermaid (this is what we are currently using to render our flowchart graphics) version in the future, download the updated version of the mermaid.min.js file and replace it in the main file structure
• In Mermaid, icons appear as icon: "prefix:suffix", pos: "x" (ex. icon: fa:face-laugh-beam, pos: "b"). The prefix tells you the icon pack and the suffix tells you the icon within the pack. I don’t know what the position modifier does but I’ve been told it’s not important.
  • To add more packs, first find what you want here, then add info to the mermaid-init.js file. To add this info, click on the little npm symbol in the top left right next to the name of the pack after clicking on said pack. Then at the very top of the page, you should see something like @iconify-json/[package]. You can use @1 to use latest minor update in major version 1 in [version], however it is best practice to use the full version number to prevent random updates from breaking code. The [alias] tag just refers to how the icons in the icon pack will be referred to in short in Mermaid diagrams (aka the prefix section from the previous example). Use the following format:

  {
    name: '[alias]',
    loader: () =>
      fetch('https://unpkg.com/@iconify-json/[package]-@[version number]/icons.json').then((res) => res.json()),
  },

example:

  {
    name: 'fa',
    loader: () =>
      fetch('https://unpkg.com/@iconify-json/fa6-solid@1/icons.json').then((res) => res.json()),
  },

• To update the glossary, just replace the glossary.csv file (keep the name the same) with the updated version and it will automatically populate the website with the updated listings and tags.
• if there is an issue with the mdbook-glossary package, raise an issue here and text/DM Arvin.