README

Published Website

This repo contains the AI Alliance Living Guide to Applying AI, 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).

This work is licensed under Creative Commons Attribution 4.0 International. To view a copy of this license, see LICENSE or visit https://creativecommons.org/licenses/by/4.0/legalcode.

Contributing New or Improved Web Site Content

First, thank you for your interest in improving this content!. Please see our Alliance contributing page for general information about contributing to any of our projects. This section provides some specific details you need to know.

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.

We Require "Developer Certificate of Origin" (DCO)

Warning

Before you make any git commits with changes, understand what's required for DCO.

See the Alliance contributing guide section on DCO for details. In practical terms, supporting this requirement means you must use the -s flag with your git commit commands.

Using the Correct Branch

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.

Editing Conventions and Tips

Links

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.

Emojis

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.

Quick Setup

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 may want the ability to preview the changes locally.

Local previewing allows you to see how any changes, even on a single page, will really look when rendered with stylesheets, etc. 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 Markdown file viewer.

Note

If you don't want to setup jekyll for previewing or if you have trouble setting it up, don't let that stop you from contributing content! Submit a PR with your changes and we'll review them in a running environment ourselves. We'll provide feedback as needed.

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 library management tool, and jekyll which is the webserver and rendering engine.

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.

Warning

The automatic setup of jekyll in the Makefile has only been tested on MacOS and it most likely doesn't work on Windows, unless you use the Linux subsystem. 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.)

So, try make view-local and see if Jekyll is installed successfully and the 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.

Tip

1. On MacOS, use ⌘-click on the URL to open it in a browser.
2. Run make help for a list of commands defined.

Publishing a New Version

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-website.sh. It takes several options:

> publish-website.sh -h
publish-website.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.

Setup Jekyll

If the "quick setup" instructions didn't work for installing Jekyll, this section provides more detailed instructions.

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-jekyll

If this fails, then see the Tips and Known Issues below.

View the Pages Locally

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 '' --incremental

The --baseurl flag effectively supports the simple URL, localhost:4000. (Without it, the URL would be localhost:4000/The-AI-Alliance/applying-ai-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.

Tip

make view-pages opens the published GitHub Pages in a browser tab.

Now Edit!

You can now edit the pages, save them, then refresh your browser to see the updates.

Tips and Known Issues

Use Homebrew to Install Ruby on MacOS (Recommended)

You really can't use the Ruby that comes with your Mac, because:

1. It's too old, 2.6.X, instead of 3.X, which we need.
2. 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 [email protected]
which -a ruby

If 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.

The Jekyll Installation Instructions Failed

Suppose you run the following command and it fails:

make setup-jekyll

First, 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-pipeline

Finally, if you are still stuck, please post an issue to get help.

Help Needed:

If you find missing steps that make setup-jekyll should 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.

The "make view-local" Command Fails

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

Configuring GitHub Pages in the Repo Settings

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.