roachbones / mcitfaq

FAQ page for Marietta College IT Department.

mcitfaq

A work-in-progress FAQ website for the Marietta College IT Department.

How it works

The actual HTML files are generated by Jekyll, a static site generator. It reads through all the files in _answers/ and uses the _layouts/answer.html template to turn them into HTML files. The files in _answers/ are just the content of the answers without all the html boilerplate surrounding it. They can be in either HTML or Markdown. Markdown is recommended because it's simpler. See _answers/zoom_safety.md for a concise example of how the answer files are formatted.

Jekyll also generates the question lists and takes care of all the linking between pages, including breadcrumb navigation.

How to add new answers

Answers go in the _answers/ folder. See the other ones for examples. Each answer starts with the following "front matter" section:

---
layout: answer
title: How to Add an Answer
topic: wifi
question: How do I add an answer?
---

• layout should always be answer for answers.
• title specifies the title of the answer.
• topic specifies the topic that the question is listed under. You can alternatively specify topics instead to make the question appear under multiple topics; see _answers/onedrive_zoom_integration.md for an example. Topics available are listed in _topics/. We can add more if we want.
• question specifies the question. This is listed on the topic page to link to the answer.

After the front matter section goes the actual content of the answer, in either Markdown or HTML or a combination of the two. I recommend using Markdown for everything except images. GitHub has a pretty good built-in Markdown editor you can use. Feel free to send me your GitHub username and I'll give you edit access.

Wait, how do I actually run Jekyll?

Here are guides on how to do it for each operating system. You can also just upload the files to this GitHub repository, since GitHub supports Jekyll, and the changes will automatically update on this live demo after a few minutes.

Is this needlessly complicated?

I don't think so. Using the generator is much quicker and less error-prone than manually writing each HTML file, and makes it much easier to make formatting changes to the whole website.