This repo contains the AI Alliance Understanding AI Trust and Safety: A Living Guide, published using GitHub Pages. We welcome contributions as PRs. See the AI Alliance CONTRIBUTING instructions. Also, you'll need to agree with the AI Alliance Code of Conduct and all contributions will be covered by the LICENSE (which is also in this repo).
We use GitHub Pages so edits can be made in Markdown, updates can be managed using pull requests, and the results can be published automatically by GitHub.
In fact, each page has Edit this page on GitHub links, making it easy to view a page, then go straight to the source to edit it and submit a PR! This is the best way to help us fix typos and make similar small edits.
However, this easy approach only supports correcting content on a single page. for more significant changes, like adding new pages, you'll want to edit and preview the changes locally.
Local previewing also helps you see how the changes will really look when rendered. While GitHub renders Markdown well, there are extensions we use that are supported by Jekyll that won't be rendered correctly in GitHub's default file viewer.
So, to view the website locally and to make more extensive changes, you'll need to have a recent version of Ruby installed, along with the gem and jekyll tools.
We discuss these steps in more depth below, but the following steps may just work for you.
Install a recent version of Ruby 3. Note that on MacOS, the default Ruby installation is old, version 2.6.10. Installing Ruby will also install the gem dependency tool.
This project's Makefile will attempt to install the remaining dependencies, including jekyll, when you run make all or make view-local, as a prerequisite task.
So, try make view-local and see if Jekyll is installed successfully and website is rendered.
The command will finish with a message like this:
...
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
Open the URL in a browser.
Tips:
- On MacOS, use ⌘-click on the URL to open it in a browser.
- Run
make helpfor a list of commands defined.
WARNING: The automatic setup of
jekyllin theMakefilehas only been tested on MacOS. If you encounter problems on other platforms, please post an issue to get help, or if you can fix the issue, a pull request (PR) is always welcome 🤓. (More details on PRs below.)
What gets displayed by GitHub Pages is the customized Markdown files in the docs directory. If you need to create a new page, copy an existing page to get the correct "header" information, then edit as needed.
Here are some things you should know.
As for most Git projects, issue PRs to the main branch. However, the repo is actually configured to publish the docs from the latest branch, so we can accept PRs quickly, then decide when to publish a new version. (We will also tag latest for each release with a version number, for historical tracking.)
Note: If you are curious, the details of how this publication branch is configured are discussed below.
Because PRs go to the main branch, but the pages are published from the latest branch, PRs are not immediately published. When it is time to publish a new version of the website, change to the main git branch and run the script ./publish.sh. It takes several options:
> publish.sh -h
publish.sh [-h|--help] [-n|--noop] [-v|--version V] [-t|--timestamp T]
Where the options are the following:
-h | --help Print this message and exit
-n | --noop Just print the commands but don't make changes.
-v | --version V Use version string "V", which should be of the format
"X.Y.Z". Without this option the current value of
"last_version" in _config.yml is extracted (e.g., 1.0.1)
and the last digit is incremented.
-t | --timestamp "T" Use this timestamp "T", which you'll need to quote on
the command line, because it must be of the form
"%Y-%m-%d %H:%M %z". Without this option, the current
system time is used.
With no arguments, the current version string's last digit will be incremented. For example, if the current version is 1.2.3, the new version with be 1.2.4. Please use this X.Y.Z format if you specify a new version explicitly. The script doesn't check the format.
The script does check that a specified timestamp uses the correct format, but it should be rare that you would want to use any timestamp other than the current time, which is the default.
Both strings are printed at the bottom of each page, e.g.:
Version: 1.0.1. Site last modified: Jun 5 2024 08:13 -0500.
For internal cross-references, use the conventional [title]({{site.baseurl}}/relative_URL) Markdown syntax.
WARNING: the
{{site.baseurl}}/prefix is essential, because this prefix will be different for local execution vs. published serving.
For external links, add a target tag using the following syntax, which works for GitHub Markdown and GitHub Pages.
[title]({{site.baseurl}}/relative_URL){:target="_target"}
The target value is arbitrary; use whatever you want. While this is a little more tedious to type, it is usually better for users so they don't lose their place in the document. Also, our stylesheet is configured to put the little up-and-to-the-right arrows after every link that isn't relative, i.e., links that start with http or https. This provides a visual clue that a new tab will be opened.
In the pages, you can use emojis, e.g., :+1: yields 👍, :smirk: yields 😏, :nerd_face: yields 🤓, etc. The jemoji Ruby gem adds this capability. Here is a list of available emojis.
We provided a basic set of instructions above for setting up Jekyll locally. Here is a more detailed set of instructions, if you need them.
First, you'll need a reasonably recent version of Ruby installed. The one that comes with MacOS is not new enough. See Use Homebrew to Install Ruby on MacOS to install Homebrew and then Ruby using the brew command.
Afterwards, the commands shown next should produce similar output that shown from Dean's machine, circa June 2024:
$ which ruby
/usr/local/Cellar/ruby/3.3.0/bin/ruby
$ ruby --version
ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x86_64-darwin23]Warning: In 2022, when we used these tools, building the website was not working with Ruby 3.2, you may still need to use 3.3 or 3.1.
For MacOS, make sure the ruby path shown is not /usr/bin/ruby, which is the old, built-in 2.6 version. Try which -a ruby, which will hopefully show the Cellar version second. If so, edit the PATH definition in your ~/.zshrc file to put the newer /usr/local/Cellar/ruby/3.X.Y/bin directory before /usr/bin/.
Now, it should be sufficient to run the following command:
make setup-jekyllIf this fails, then see the Tips and Known Issues below.
Once Jekyll is set up, you can serve the pages locally for previewing and editing by running the following command, then open localhost:4000 in a browser.
make view-local # Or use "make all" or just "make"!If this throws an error, see the Tips and Known Issues below.
Tip: In MacOS terminal windows, you can ⌘+click any URL printed to open it in a browser!
The make target runs the following command:
cd docs && bundle exec jekyll serve --baseurl '' --incrementalThe --baseurl flag effectively supports the simple URL, localhost:4000. (Without it, the URL would be localhost:4000/The-AI-Alliance/trust-safety-user-guide/.) The --incremental flag lets you edit the pages and refresh the browser tab to see the updates immediately.
Note: Well, more or less immediately. It can take several seconds for new pages to be generated and sometimes you'll get weird behaviors if you change URL paths, etc. So, occasionally it is useful to control-c in the terminal and rerun
make view-local.
Pro Tip:
make view-pagesopens the published GitHub Pages in a browser tab.
You can now edit the pages, save them, then refresh your browser to see the updates.
You really can't use the Ruby that comes with your Mac, because:
- It's too old, 2.6.X, instead of 3.X, which we need.
- You don't have permissions to install Gems into
/Library/...
So, install Homebrew, if you haven't already. Then use it to install a local, recent version of Ruby:
brew install ruby@3.3
which -a rubyIf the last command shows /usr/bin/ruby before a path like /usr/local/Cellar/ruby/3.3.0/bin/ruby, then you will have to edit your ~/.zshrc file and make sure the /usr/local/Cellar/ruby/... path comes before /usr/bin. For example, the following line will just put this Ruby first. (this is a hack):
PATH="/usr/local/opt/ruby/3.3.0/bin:$PATH"(Use the exact version number you have!)
Then in your terminal, either open a new window/tab or run the command source ~/.zshrc to load the changed PATH. Now which ruby should return a path in /usr/local/Cellar/... and ruby --version should return the correct 3.X version.
Suppose you run the following command and it fails:
make setup-jekyllFirst, make sure you are using a valid version of ruby, as described in the previous section. A symptom you didn't do that? You'll see this error message:
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.
The commands run by make setup-jekyll discussed previously include the following (a few details omitted for simplification):
gem install jekyll bundler jemoji
bundle install
bundle update html-pipelineFinally, if you are still stuck, please post an issue to get help.
Help Needed: If you find missing steps that
make setup-jekyllshould run but doesn't, or you find and fix problems that only occur on non-MacOS platforms, please submit a PR with fixes! Thank you.
What if make view-local command fails with this error message?
jekyll 3.9.2 | Error: No such file or directory @ rb_check_realpath_internal
First, that's an old Jekyll version. It should be 4.3.3 or later. Try these commands:
gem uninstall jekyll
gem install jekyll
gem list | grep jekyll
This section documents the one-time settings changes we did to configure publication of our GitHub Pages. We changed the desired branch to use, latest, rather than the default main branch, and we specified the directory for the website pages, docs. This only needs to be done if and when the branch or directory location is changed.
In the repo's Settings > GitHub Pages section, set the branch to be latest and the folder to be /docs. The reason for using latest rather than main, is to allow small changes to be made without affecting what is published until we decide to publish an update.