Microsite Cheat Sheet

For those people working with the microsites, e.g., those sites cloned using microsite-template, here is a cheat sheet for working with them. See also the microsite-template README-template.md for more details.

References

First, here are some useful reference links and other notes:

• The “pretty” website for our GitHub organization : the-ai-alliance.github.io/
• The actual landing page: github.com/The-AI-Alliance/ (same content…)
  • The list of repositories (“repos”).
• The microsite-template, which is cloned to create microsites: github.com/The-AI-Alliance/microsite-template
  • The instructions for using the template: README-template.md

Need a Text Editor for Your Mac?

Unfortunately, there is one step you have to do on your laptop as part of cloning and using the template. You don’t need a text editor suitable for source code, but it might come in handy. You can install Visual Studio Code, an “IDE” (Integrated Developer Environment) that is very popular with developers, but it can be more than you need.

This website lists some free text editors you might install. Of the ones listed, Dean has either tried the following ones or they look like decent, easy-to-use options:

• MarkText, Pine, MacDown, Markdownify, and Zettlir: Limited to Markdown, the simple alternative “markup language” that is translated to HTML and easier to write than HTML, although not as full-featured as HTML. You can use either language in your sites. Since our microsites mostly use Markdown, with occasional use of HTML, one of these editors may be all you need.
• TextMate: Full featured; not limited to Markdown. This was once Dean’s primary editor. Lightweight and easy to use.
• SubEthaEdit: Full-featured; not limited to Markdown. Dean used this one several years ago.

The editors with vim or emacs in their names will have a bigger learning curve, although they are very capable.

Using the Microsite Template

To create a new website, open the microsite-template repo page. On the upper right-hand side, click the green menu button, Use this template, then Create a new repository.

• Leave Include all branches unchecked.
• Pick the desired GitHub organization (e.g., The-AI-Alliance)
• Provide a unique repository name.
• Provide a description (recommended, but optional).
• Select Public or Private. Most sites should be public, but you may wish to edit the content before making it public. (Note that the more detailed instructions in the microsite-template repo for publishing the website won’t work until the repo is public.)
• Click Create repository.

Now clone the site locally.

• Open the Terminal app.
• Run the following commands. Replace my-site with your chosen repository name in the following:

git clone git@github.com:The-AI-Alliance/my-site.git
cd my-site

Finish the initial edits by running a “shell” script that substitutes placeholders for desired string values.

• Run ./finish-microsite.sh --help to see available options.
• At a minimum, you’ll need to decide on the human-readable title/name for your site and which focus area the project belongs to. I’ll assume fa3 in what follows.

Run this command, changing the title and work group, as appropriate:

./finish-microsite.sh --microsite-title 'My Amazing Microsite' --work-group fa3

See the additional instructions in README-template.md.