Websites, Markup, and Markdown

Monday, 19 September 2016

This week's tasks will involve some very simple coding (markup, really) and continued exploration and use of our system administration skills.

Last in the git and Github lab we learned how to set up a very basic website using Jekyll and GitHub pasges. This week we will expand on that significantly, learn how to use markup to change the style of our content, and then learn to publish content to the web.

Q&A

Servers and their purposes:
- github.com hosts our code and cloneable github repositories
- github.io builds & hosts our websites
- c9users.io will show our site if jekyll serve is running. This process in the server starts a temporary server which will show code you haven't committed or pushed yet. Push your code to github.com and github.io will display it for you. If your github.io site didn't have the final version of your code (i.e. you didn't commit & push it), I had to evaluate whatever was there.
What I was looking for:
- 3 posts
- customized colors
- (at least) 4 commits separating these things

More on this today, but in Markdown, spaces matter:

#This is a hashtag in front of a sentence

# This is a h1 heading in markdown

...end of some text.
* this is not a list

...end of some text.

* this is a list (note empty lines above and below)

What do you need to understand to move forward? Get help and get that out of the way.
Something take you a long time? Practice, practice, practice!

Why did we do multiple commits? Let's Revert some color changes! I need a volunteer.

In class mini-exercise:

get jekyll running with jekyll serve --host $IP --port $port
get another terminal open
git log and get the first few characters of the commit where you made colors changes
Add a commit (maybe adding a word to a post) after your colors changes if you don't already have one. This is so you can see that we can revert a commit even after other ones have been made.
Run git revert [commit hash]
this will revert the commit (as a new commit itself)bring up nano and an autogenerated commit message. Ctrl-x leaves. If you made changes, y says yes you want to save and confirm the filename with Enter
Start with just one colors commit if you have multiples. But yuo can repeat the process for others outside of class.
git log to see what happened
Check your c9users.io site to see your un-colored site!
Commit in revertable chunks!

Now, let's learn some things about markup.

Markup and Markdown

Mark*up* has been used over the last several decades to enhance plaintext for web use.

Today we will consider some of the basics.

Markdown is a markup language, but designed to be as simple and human-readable as possible. We had a brief introduction to it last week when we established our first repositories on GitHub.

Why are we learning Markdown?

For starters, Markdown is easier to use than HTML or other markup languages. It doesn't require complicated tags, which have a high potential for typographical error.

Jon Mitchell posits the three following good and compelling reasons that everyone should learn Markdown:Mitchell, Jon. “3 Reasons Why Everyone Needs to Learn Markdown - ReadWrite.” ReadWrite. Last modified April 17, 2012. http://readwrite.com/2012/04/17/why-you-need-to-learn-markdown/.

It is easy to read.
You will make fewer errors.
It helps us to get rid of buggy, crashy, loss-prone content management systems (CMS).

All of the above boils down to a simple comparison that Mitchell makes:

HTML:

<h1>Why <em>you</em> should use Markdown to write your next blog post</h1>

<p><a href=”http://daringfireball.net/projects/markdown/”>Markdown</a> is just so dang legible, it will make your <em>whole life</em> easier. <strong>I promise.</strong></p>

Markdown:

# Why *you* should use Markdown to write your next blog post

[Markdown][1] is just so dang legible, it will make your *whole life* easier. **I promise.**

[1]: http://daringfireball.net/projects/markdown/basics

The above examples render the same thing when parsed. Which would you rather write? Which is easier to read?

We will go over some of the basics in class today, but I would also like you to review the resources listed here independently, outside of class. Review: “Mastering Markdown.” GitHub Guides. Last modified January 15, 2014. Accessed June 27, 2016. https://guides.github.com/features/mastering-markdown/.

This guide is oriented toward GitHub, but the skills represented there extend well beyond that context.

We will work interchangeably in HTML and Markdown over the course of this next section.

HTML5

HTML is an initialism for "HyperText Markup Language."

"Hypertext" is text that contains links to other text.Keith, Jeremy. “A Brief History of Markup.” A List Apart 305 (May 4, 2010). http://alistapart.com/article/a-brief-history-of-markup. The Web, as we know it, relies on hypertext to for us to communicate with systems and with other humans. It is the medium of Web content.

HTML5 is the latest iteration of a standard related to the writing of web content. Web markup has a long history over the last few decades, beginning with Tim Berners-Lee, one of the fathers of the modern web (and the inventor of HTML). Berners-Lee proposed the creation of an information management system for the European Agency for Nuclear Research (CERN) in the late 1980's.Berners-Lee, Tim. Information Management: A Proposal. European Agency for Nuclear Research (CERN), March 1989. Accessed June 27, 2016. https://www.w3.org/History/1989/proposal.html.

When we write Markdown and then post it to GitHub, a system actually translates it into HTML5.

For next time

I would like you to look at this tutorial about creating a website using Jekyll and GitHub Pages. ⊕Reading: Clark, Barry. “Build A Blog With Jekyll And GitHub Pages – Smashing Magazine.” Smashing Magazine. Last modified August 1, 2014. Accessed June 27, 2016. https://www.smashingmagazine.com/2014/08/build-blog-jekyll-github-pages/.

We have already done this in a very rudimentary way, but we will do it again to create a better final product.

Homework: Pick a theme

Spend some time going through these and selecting one you like. I'll help you customize it so it works with Github pages. If you've got experience with web design or want to be more adventurous, check some of the more challenging themes. They should all be a similar level of difficulty after the initial setup. We're not using any of the more complicated Jekyll plugins that you have to pre-build.

Some easy themes

http://jekyllthemes.org/themes/basic/

https://github.com/henrythemes/jekyll-bootstrap-theme/

https://github.com/henrythemes/jekyll-minimal-theme/

http://jekyllthemes.org/themes/devjournal/

http://jekyllthemes.org/themes/gravity/

More challenging themes

http://jekyllthemes.org/themes/jekyll-clean/

http://jekyllthemes.org/themes/thinkspace/

http://jekyllthemes.org/themes/vitae/

http://jekyllthemes.org/themes/dbyll/

http://jekyllthemes.org/themes/blackdoc/

http://jekyllthemes.org/themes/daktilo/

Clone and make a new repo for your site

Once you have chosen a Jekyll theme for your site, Clone it into a fresh Blank Cloud9 workspace.

Later, together, we will make a new repository for it that you own, Push to that repository (following the instructions that pop up when you make a new repo), make appropriate changes to turn it into our own, and then you can get to work on customizing the look and feel of the site.

When we make changes to Jekyll's configuration, we are ostensibly telling it where to find different necessary files for rendering the site, like our CSS file.

Good advice:

"Write the best code possible today and be completely unattached to it and willing to delete it tomorrow."https://t.co/mBAJhip0KP
— Adam Wathan (@adamwathan) June 27, 2016