Eastbots Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
Our [[https://eastbots.com | team website ]] is hosted at [[https://pages.github.com/ | github.io]], and is built using github.io's default template engine, [[https://jekyllrb.com/docs/ jekyll]].
Woah, that's a mouthful already.  TODO: step back and explain a little about all of those links.

A student did a quick prototype of a site redesign.  It consists of several pages, written in standard html using a popular stylesheet package called [[https://getbootstrap.com/ | Bootstrap]].  (TODO: host one of those pages somewhere so we can point to it)

This page explains briefly how we took that new site design, and transplanted it into the same underlying structure, getting a fresh new look with all of the benefits.

Looking at the html pages of the prototype site, we see that each one has a lot of code that is the same, and some content that's different.  The point of the template system is to store the parts that are the same only once, so they can be updated easily.  We start with the simplest pages, that just have the navigation bar and some content, for example the "contact" page. The HTML for that page has the following parts  
  * top stuff, including the ''<head>'' section
  * some stylesheet overrides
  * navigation menu bar
  * text content, that changes for each page. 
  * footer
The "resources" page is identical, except for the text content.

So, where do those go in the jekyll site?

===== head.html =====

Most of the guts of the ''<head>'' section and related stuff goes into ''_includes/head.html''

It looks like:
<code>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="description" content="">
<meta name="author" content="">
<link rel="icon" href="../../favicon.ico">
<title>{{ page.title }}</title>
<!-- Bootstrap core CSS -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
<style>
{% include css/default.css %}
</style>
</code>

Only one tiny piece of of this file isn't copied verbatim from the prototype site design:  
the HTML ''<title></title>'' section.  Here, we refer back to the original jekyll site, or the documentation,
and put in ''{{ page.title }}''.  This little bit of magic gets replaced with the actual title of each page
as it gets generated.

===== Navigation Bar =====

The navigation bar code goes into ''_includes/nav.html''.  It is also copied verbatim from one of the handcrafted pages.  Be careful to include the correct matching ''</div>'' for each ''<div>''.

We also preserve the google analytics code that was in the old website.

What nav.html looks like

===== footer html =====

Our page footer consists mainly of a copyright symbol and a date.  ''_includes/foot.html ''contains
<code>
<footer>
    <p>&copy; Eastbots 2019</p>
</footer>
</code>

===== end-of-page code =====

Taking another cue from the old jekyll website, we look at the new html for common code that goes at the bottom of every page body.  In ''_includes/end.html'' we copy the
javascript includes used in the new page, which happen to match those in the [[https://getbootstrap.com/docs/4.3/getting-started/introduction/ | Bootstrap documentation]]

link to end.html in github.

===== Layout template for a page =====

With those include files set up, we can now stitch back together most of the standard pages in the new site.

Page layouts are done with templates in the ''_layouts'' directory.  Mostly they're very short, and contain a little bit of HTML and some jekyll-syntax include statements.

Here's ''_layouts/standard.html'' in its entirety:

<code html>
<!DOCTYPE html>
<html lang="en">
<head>
{% include head.html %}
</head>
<body>
  <div id="page-wrapper" class="container-fluid p-0">
    <!-- Navigation bar -->
    {% include nav.html %}
    <!-- Main body -->
    <div class="container">
        <div class="starter-template" id="post">
            <h2 align="center">{{ page.title }}</h2> {{ content }}
        </div>
        <hr> {% include footer.html %}
    </div>    <!-- /.container -->
    {% include end.html %}
  </div>
</body>
</html>
</code>

The best thing about these layout templates is that they're short, and serve as an outline of the whole page.  With the reusable pieces broken out into files, ''_layouts/standard.html'' reads just like the bulleted list of pieces that we started with above.

Some of the things we see in there are the include statements for head, nav, and end; they look like
''{% include nav.html %}''

There's also ''%%{{page.title}}%%'' again, and  ''%%{{content}}%%'', which gets replaced with the markdown
content for the page.

====== Page Content ======

Finally, we get to put together a page.  The new "Contact Us" page consists of three short 
paragraphs of text.  The markdown source for that page goes into ''contact/index.md''
and starts off with a simple header:

<code>
---
title: Contact Us
layout: standard
---
</code>
Unless you know what you're doing (or have read more markdown documentation than I have)
put four lines exactly like these into the .md file for each page.  That's:
  * three dashes
  * title: followed by the actual page title
  * layout: followed by the name of the page layout template, here ''standard'' means to use ''_layouts/standard.html''

The file continues wiht the actual text for the page, starting with:

<code>
To contact the Eastbots, please email us at <admin@eastbots.com>, and our team will get back to you as soon as possible.
</code>

Note that the markdown content can include some html, but that it generally doesn't have to.  Just type plain text, and seperate each paragraph with a blank line, and your text will get formatted up nicely.


====== The Home Page is Special ======

The main home landing page is special: it doesn't use the "standard" layout.  It has its own layout,
''_layouts/home.html'', which includes some additional css to set up the transparent "card" overlayed on top of a big background image.

The text in the card comes from the to level ''index.md'' file.

We actually could just put the whole thing into a single html file in the github repo, but breaking it up this way is useful for several reasons:
  * we can reuse this layout if we want.  
  * the text can still be edited in its own markdown file, even by someone who doesn't understand html or the rest of the site
  * an opportunity to learn more jekyll

''_layouts/home.html'' is still a concise outline of what goes into the page:

<code html>
<!DOCTYPE html>
<html lang="en">
<head>
{% include head.html %}
<style>
{% include css/home.css %}
</style>
</head>
<body>
  <div id="page-wrapper" class="container-fluid p-0">
    {% include nav.html %}
    <div id="info-card" class="card shadow-sm">
      <div class="card-body">
	<div class="card-text">
	  {{ content }}
	</div>
      </div>
    <hr>
    {% include footer.html %}
  </div> <!-- /container -->
  {% include end.html %}
</body>
</html>

</code>


TODO get this page up too.