Contents

Ways you can help improve this website

We need help! Here are a few ideas for how this website might be improved. If you would like to do one or more of these things, whether or not you are currently enrolled in AE353 at Illinois, contact Prof. Bretl.

Add a sidebar with the table of contents

It would be nice to have the table of contents in a sidebar that is always visible, instead of at the top of the page. Leap Day is a theme for GitHub Pages that has this kind of sidebar (see demo). You could either change the theme of the site from Cayman to something like Leap Day, or add a custom sidebar to the Cayman theme.

Improve site navigation

There is a row of buttons in the header that allow movement between pages on this site. There are a number of problems with this at the moment:

There are various third-party Jekyll themes that support this sort of thing, such as Hyde. I don’t know how to use third-party Jekyll themes. You could figure that out.

Tips and tricks for site creation

Including a table of contents

This website was created using Jekyll on GitHub Pages. If you look at the code, you’ll see that content is written in Markdown. By default, Jekyll uses kramdown to convert Markdown to HTML. Kramdown supports the automatic generation of a table of contents. This table will include an entry for every header. To use this feature, you include the following lines at the top of your Markdown document:

## Contents
{:.no_toc}

* This text will be replaced by a table of contents (excluding the above header) as an unordered list
{:toc}

The {:toc} tag is what creates the table of contents. The {:.no_toc} tag ensures that the header “Contents” will not appear in this table. Note that you must put {:toc} on its own line immediately after a single list item. The text in this list item will be replaced.

You might think it is silly to include a line of text that will simply be replaced. In particular, it might seem reasonable to do this instead:

## Contents
{:.no_toc}

{:toc}

Don’t! This will not work.

How to preview this website on your own computer

It is helpful to preview changes I make to the website before they go live. To do so, I followed these instructions from the GitHub pages documentation.

First, I installed ruby, bundler, and jekyll. I used Homebrew to install Ruby. I did not use rbenv.

Second, I created a Gemfile and installed dependencies. If I had been starting from scratch with a new repository, I would have followed these instructions from GitHub. However, I had already created a site, so instead I did the following things:

Third, I tested the site by following these instructions from GitHub. In particular, still inside the docs/ folder, I called

bundle exec jekyll serve --baseurl '/ae353-sp21' --livereload

and then opened http://localhost:4000/ae353-sp21/ in a browser. The --livereload argument (see docs on serve command options) makes it so the browser will automatically refresh with each change made to source files. See “Clearing Up Confusion Around baseurl – Again” for why the --baseurl '/ae353-sp21' argument is necessary.

The key benefit of this setup is that any local changes I make to files (e.g., this one: howto.md) show up immediately in my browser on localhost. In contrast, if I git push these changes, it can take several minutes for the site to rebuild and for these changes to show up in my browser on tbretl.github.io/ae353-sp21.

It took several hours to figure this all out. There were three causes of delay:

If I did this all again, it would take no more than ten minutes.

How to create an Illinois Media Space channel that accepts student submissions

Create a channel on Illinois Media Space in the usual way (also see video tutorial). Set permissions to “Shared Repository”.

You will probably want to keep this channel private so that only enrolled students can view and contribute content. This is done by “Rostering a MediaSpace Channel with Students Enrolled in a Course”. In particular, follow these steps:

At this point, all enrolled students (and nobody else) will be able to upload videos to this channel and view videos in this channel.