Website Skeleton: a template for your site
The canonical site is https://github.com/maruel/webskel. Please read the instructions there as they may have been updated.
Features
- Flexible. Create:
- A static web page site (e.g. small website for a small shop, personal page, etc) that is not meant to be updated frequently.
- A full featured blog.
- Or both!
- No programming needed at all! Complete site can be deployed only with a web browser.
- Instructions included below to get free web hosting and free HTTPS support for a professional look.
Further;
- Mobile first design. Looks great on mobile and on desktop.
- Retina-ready icons for popular web sites to look great on
iPhone/iPad/MacBook Pro/etc:
- Includes meta data for Facebook, Twitter, Google and Bing. When a user shares a link to a page on your web site, Twitter/Facebook/etc will automatically generate the right summary based on the page content, including your Twitter account reference, company logo as specified in config.toml, etc.
- Includes everything to be indexed by Google and Bing including great snippets.
- Google Analytics support to track your audience.
- The code was handcrafted to be very efficient and easy to read and modify.
Prerequisites
- Buy a domain name. If you don't know what registrar to use, try Google
Domains, it's cheap and privacy registration is
free. The following assumes you are using Google Domains.
- This document uses
your.domain
as your domain name. Replace it with yours.
- This document uses
Accounts
The instructions below assumes you are logged in into these 3 accounts:
- Visit github.com. Click
Sign up
and chose the Free plan.- Every time you see
USER
in the instructions below, replace it with your GitHub user account name.
- Every time you see
- Visit codeship.com. Click
SIGN UP FOR FREE
.- Choose
SIGN UP WITH GITHUB
. - Click
Authorize application
. Stop there and leave the tab open.
- Choose
- Visit cloudflare.com. Click
Sign up
and create an account. Stop there and leave the tab open.
Steps
- Visit github.com/new. Create a new repository
named
USER.github.io
. ReplaceUSER
with your GitHub username. This will contain the actual files of the website. ClickCreate repository
. - Visit github.com/maruel/webskel. Click
the
Fork
button at the top right. - At this point, you have two repositories:
USER.github.io
andwebskel
. - You should be on github.com/USER/webskel,
as usual replacing
USER
with your GitHub username. - The files in
content/
,layouts/
contain a lot of comments and things to update. Read the files, it will define the look and feel of your page and will setup the initial metadata (your picture, email address, etc). - For every file below, click on it, click the small pen Edit button.
Replace every instance of
CHANGE_ME
with the relevant content. For example foremail
, use an email address you want to appear on your website, if desired. For every file, save the change to generate a commit. The files that need to be changed are:- config.toml; This file is the global website's settings. It is the most important file.
- layouts/index.html; This file is the root page of your website.
- layouts/partials/header_common.html; This file is injected at the top of every pages on your web site.
- static/CNAME; This file tells GitHub what is your domain name.
- content/page/ is where you put non-blog pages like about you or a page describing the company. You can add as many as you want. You can delete the default ones too.
- content/post/ is where the blog posts are located. This
is optional.
- content/post/new.md; This is an example of a blog post.
- Visit codeship.com to activate your codeship
project.
- Click the big green button.
- Click the awkward GitHub button.
- Select
USER/webskel
. - Scroll down to
Configure Test Pipelines
section at the bottom, remove all the text in the black edit box and type:./generate.sh
- Codeship is a bit tone deaf and requires you to make a change to your repository at that point, so go back to github.com/USER/webskel, edit a file, make a dummy change and commit it.
- Once you did a change, go back to codeship.com and
there should be a
RUNNING
build that eventually becomesSUCCESS
. - Click
Project Settings
at top right. - Click
Deployment
. - Type
master
. - Click
Save pipeline settings
. - Click
Custom Script
(the last item). - In the black edit box, type:
./publish.sh
- Click
Create
. - This enables the conversion of sources from
webskel
into the website atUSER.github.io
everytimewebskel
is changed.
- Now you need to fix something. Codeship has added its private key to
webskel
but we want it to push toUSER.github.io
so we need to make a small change:- Click
General
on the left. - Copy the
SSH public key
; it's a long string starting withssh-rsa AA
... Select it all and Ctrl-C. - Visit github.com/USER/webskel/settings/keys.
- Click the red button Delete.
- Visit
github.com/USER/USER.github.io/settings/keys.
Click Add deploy key.
- Title use
codeship
. - Ctrl-V (paste) the SSH public key there.
- Click
Allow write access
. - Click
Add key
.
- Title use
- Click
- Visit cloudflare.com/a/setup to enable
HTTPS serving.
- Type
your.domain
at the bottom. - Wait 60 seconds and click
Continue
. - Choose
A
, Typeyour.domain
as Name,192.30.252.153
, click Add Record. - Choose
A
, Typeyour.domain
as Name,192.30.252.154
, click Add Record. - Choose
CNAME
, Typewww
as name,your.domain
as Domain name, click Add Record. - For Google Domains only;
- Choose
MX
, Type@
, Selectgmr-smtp-in.l.google.com
and5
- Choose
MX
, Type@
, Selectalt1.gmr-smtp-in.l.google.com
and10
- Choose
MX
, Type@
, Selectalt2.gmr-smtp-in.l.google.com
and20
- Choose
MX
, Type@
, Selectalt3.gmr-smtp-in.l.google.com
and30
- Choose
MX
, Type@
, Selectalt4.gmr-smtp-in.l.google.com
and40
- Choose
- Click
Continue
. - Click
Free plan
, ClickContinue
. - Visit domains.google.com/registrar
to assign DNS server from Google Domains to CloudFlare.
- Click your domain name.
- Make sure that email forwarding is configured.
- Click the 3rd button
Configure DNS
. - Click
Use custom name servers
. - Type
bonnie.ns.cloudflare.com
, click+
. Typefrank.ns.cloudflare.com
and click Save. - You have to wait a while for CloudFlar serving to be enabled. It can be a good hour. Go grab a lunch.
- Type
Optimizing
- Visit google.com/webmasters/tools/home to setup Google search settings.
- Visit bing.com/toolbox/webmaster to setup Bing search settings.
- Visit www.google.com/analytics to get data about the audience.
Adding or editing content
You should now visit https://your.domain and see your new website.
To add a new page or a new blog post:
- Visit
github.com/USER/webskel/tree/master/content/page/).
In practice, click through from
github.com/USER/webskel on
content
, thenpage
. Usepost
for a new blog post. - Click on the little
+
at the top next to thepage
word. - Give a name to your file. This will become part of the URL so use something nice.
- Write content. Use the following as the initial content of the page:
+++
# Lines starting with a # are comments.
# For `page` content, use 0001-01-?? as the date, the day is used to order the
# pages in reverse order. It will not be shown, it is only used to order the
pages in the toolbar # at the top.
#
# For `post` content, use today's date. It will be shown everywhere the post is
# listed.
date = "2015-01-01"
# The title of the page should be short. It'll be shown at the top of the page
# and will be used when shared on Facebook/Twitter:
title = "Title of the page"
# The summary is slighly longer but should still be short, under 200 letters. It
# will also be used on Facebook/Twitter and will appear on Google's search
# result snippets.
summary = "Short summary of the page"
# The actual content starts after the following line:
+++
Enter content here.
- Modify the content: use GitHub Flavored
Markdown
reference page for how to format your page.
- https://help.github.com/articles/markdown-basics/ gives basics.
- https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet is an unofficial visual help guide that may be more helpful.
- Click the green button
Commit new file
. - Wait one minute for codeship to process your new commit.
- The new page should be live on the website as Codeship generated the new website.
Local viewing
To iterate faster, it is useful to look at the website locally so you can look at changes and see the effect immediately. Hugo is great in this case since the webpage updates automatically as you save a file. Follow these steps:
- Visit gohugo.io. Click Download and download the right version for your computer. Then install it.
- Run:
hugo server -w
- On OSX or Linux, you can use instead:
./serve.sh
The reason is that it opens the website to the local network, which permits looking at the website via a tablet or a phone to confirm the mobile experience is good. On Windows, you have to usehugo server --bind=0.0.0.0 -w -b MACHINE_NAME
whereMACHINE_NAME
is the name of your computer on the network.
- On OSX or Linux, you can use instead:
Credits
Services
Thanks to all 3 services (GitHub, Codeship and CloudFlare) making this possible for free:
- Static files hosting is done through github personal pages. The redirection from http://your.domain to https://USER.github.io is done via CNAME file.
- Continuous deployment is done via https://codeship.com, so that modifying MarkDown files via GitHub's UI automatically regenerate the site and deploys automatically.
- HTTPS serving is done via https://cloudflare.com. It also does the transparent https://your.domain -> https://USER.github.io conversion under the cover.
Software
Thanks to these projects to simplify making a mobile-first website for free:
- Uses Hugo to convert markdown files into a static
site.
- It is programmed in Go.
- CSS is based on https://bootswatch.com/yeti/ by Thomas Park. Code released under the MIT License.
- Uses bootstrap and jquery for a mobile first experience.
License
This software is copyrighted Marc-Antoine Ruel. It is licensed with an Apache 2.0 license.