-
Notifications
You must be signed in to change notification settings - Fork 9
Blog
The blog on the website, at first glance, can be a rather complicated mess of code and style-sheets. However, once you know how the pieces of the website work together to automatically generate web pages, it quickly turns into something that anyone could figure out how to update and maintain. The main driving force behind using this method of auto-generation of content, is to make it as easy as possible for future people to add updates to the website, and for others to learn how to create a website like this one.
Every page on the website, with the exception of the blog itself, is automatically generated using templates from the /_layouts directory. The blog itself uses a layout that is defined in /blog/index.html, which in turn derives from the /_layouts/page.html to make sure that it looks the same as all of the other pages on the website.
All of the blog posts themselves, use the template found at /_layouts/post.html, which is automatically applied by putting files into the /_posts directory. This template describes where things like where the title is, how the cover images are placed, and how to tags are added. The actual look and feel of the blog; in terms of colors, fonts, and spacing, is all defined in the /_sass/blog.scss, which is automatically generated into style-sheets for the website. For the most part, there isn't any need to update this style-sheet when adding new posts.
To add a new post, it is as easy as adding a new file in the /_posts directory, with the filename using the following scheme: YYYY-MM-DD-title-of-the-post.md. Where the YYYY-MM-DD section defines when the post should be "posted", and using a date in the future will automatically hide the post until then. The title section of the file can be used for setting the title of the blog post with dashes in place of spaces, but can be changed later from within the file. So it's best that the title that is used here is, at the very least, unique and descriptive to make finding it later easy.
The top of any blog post needs a bit of information called "front matter", with starts and ends with ---. This front matter allows you to set the author of the post, add a cover image, add tags to the post, and change the title. An example post has already been placed in that directory that allows anyone to use as a reference for creating new blog posts.
Following the post front matter, comes the post excerpt, or preview text, of the blog post. This text is used when rendering the preview of the blog post on either the front page, or on the blog page. After the excerpt, comes the body of the blog post. The body and the excerpt are separated using <!-- excerpt --> between them.
For the post body itself, all you need it to type. All of the formatting is handled automatically when the file is used to generate a web page. Paragraphs are separated using blank lines, and things like italic text and bold text can easily be inserted using this guide.
Images aren't explicitly required for a blog post. However, every blog post really should have at least one cover image for when it is presented on the front page, in the blog posting, and for when it is shared on social media. To add cover images, the URLs to them are added to a list called cover-images in the front matter section. If multiple images are listed, then the first one in the list will be used as the preview image for the blog post.
Adding figures to any web page are slightly more complicated. Figures use a building blocks are saved in the _includes directory, and included onto the page by adding {% include figure.html %} where you want the figure to be place on the page. Figures will always be placed on the left hand side of the main page content, but can be changed to the right hand side by adding position="right" as an argument to the include line. Figures will always render next to the content that immediately follows it within the blog post, so keep this mind when placing them next to things within blog posts. The content of the figure is set by using the image argument with the URL of the image you'd like to be in the figure; the html argument with raw html for including things like a YouTube video, or a Google Maps iframe; and setting the caption argument for adding a caption to the figure.
Here are a few examples of how to add content in a few different ways:
{% include figure.html image="/assets/img/people/medley.jpeg" position="right" caption="Br. John Medley dual wielding statue irons."%}{% include figure.html image="https://blog.travis-ci.com/images/student-developer-pack-logo.png" %}{% include figure.html html='<iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d2714.941430962724!2d-88.556049884476!3d47.119819279155394!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x4d50c8238322281b%3A0x137b0e36c451b81!2s1307+Ruby+Ave%2C+Houghton%2C+MI+49931!5e0!3m2!1sen!2sus!4v1520549347901" width="400" height="300" frameborder="0" style="border:0" allowfullscreen></iframe>' position="right" caption="The location of the new chapter house." %}
All pictures for blog posts should be placed in /assets/img/posts, unless they are used in other places on the web site. Under no circumstances are SnapChats, or other vertical images taken from cell phones, acceptable for the website. They are extremely unprofessional looking and will rarely render correctly on the website. Images that are used, should have an aspect ratio of 16:9 at the very least, should be high resolution, and contain respectable content.
Similar to adding cover images, tags can be added to posts to allow readers to easily find other related blog posts. Blog posts are tagged by adding capital title case title of the tags to a tags list in the front matter section of the blog post. To see a list of available tags, look in the /_tags directory or the blog itself for a list of what tags are currently available.
Adding new tags is rather easy. Just add a *.md file to the /_tags directory, where the filename is the title of the tag. These tag files must contain a front matter section, but it may be empty. Similar to blog posts, you can also set the title of the tag by using the title option in the front matter. You can also add a description of the tag to the body of the markdown file, but is not explicitly required.
Here is an example of the bare minimum contents of the tag markdown file.
---
---
One of the first posts that was made, and a great example to creating your own posts, is this one about the 2017 Winter Carnival statue, the source of which can be found here.