Adding schema.org to a GitHub Pages site
This guide will show you how to do add schema.org to GitHub Pages.
Github Pages
GitHub Pages are an excellent platform for creating informative websites. The hosting is (currently) free which is a huge plus; the collaborative tools allow teams (that may be widely distributed, fluctuating, and/or voluntary) to contribute in a well-structured, verifiable, and open manner; and the version control capabilities are a must in any software project. It’s becoming an increasingly popular choice to make websites with. GitHub Pages makes use of the Jekyll templating engine.
In this tutorial we will set up a new Jekyll site to share our training materials with, and mark-up them using schema.org.
Setting up a new Github Page site
First things first, follow this guide to setting up Jekyll and hosting it on GitHub pages. Once you've got the correct environment setup, you can then create a new app by running jekyll new my-tutorials
In this tutorial we will work with a file structure like below. Something similar to the below should be generated once you generate a new Jekyll site, except for one or two difference. Firstly you can delete/ignore the folder_posts, and secondly we will add two folders called _tutorialsand _layouts.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _layouts
│ └── tutorial.html
├── _tutorials
│ └── awesome-tutorial.md
├── about.md
└── index.md
Lets create our first tutorial called awesome-tutorial.md in the _tutorials folder.
Adding metadata to your pages
Open awesome-tutorial.md and copy the snippet below into it. Jekyll allows you to put what's called Front Matter at the top of markdown file in YAML syntax. Front Matter contains variables, metadata, and layout configuration options. It must be surrounded by 3-hyphens above and below. Beneath that we can add the mark-down content of the webpage.
Here we define how to render the page (Line 2), what our metadata is (Line 3-18), and what the page contents will be (Line 21-27).
The first two properties specify which vocabulary we are using - the CreativeWork vocabulary ("@type": CreativeWork) from schema.org ("@context": http://schema.org/).
You will use a different schema type depending on which schema.org vocabulary you are describing (e.g. "@type": Event for events, "@type": Website to describe what your website is, or "@type": Recipe to describe a potato salad)
Lines 6-18 is a list of key-value pairs. Each key is a property of the CreativeWork vocabulary (e.g. Keywords, Description, Name) along with its value (e.g. ["schemaorg"], "In order to establish...", Adding schema.org..."). The full list of properties, the expected types, and examples on how to use them are all available on vocabulary pages in http://schema.org/CreativeWork.
We’ve also added layout: tutorialto our YAML. This tells Jekyll (the underlying framework) that this page should be rendered as part of a HTML layout template called tutorial.
Rendering your Metadata
Lets create a new folder called _layouts and have a new empty file called tutorial.html inside. This is where our HTML template used to render our tutorial will be.
Open tutorial.html and add the following:
This will be the basic layout of on any page that specifies layout: tutorial in it's YAML.
When loading a page that specifies this layout, Jekyll will render tutorial.html and inject the contents (Line 21-27) where the {{ content }} tag is. The metadata defined in Lines 2-18 can all be access by their keys.
To render our schema.org we pass the schemadotorg metadata to the jsonify function. This will convert our schemadotorg keys and values into one of the schema.org supported data-formats; JSON-LD.
Before we can test this, we need to install the jsonify function. Open the file called Gemfile located in the root directory, and add the following lines:
Now, in your terminal you can run bundle install to install the jekyll-json-ldgem (see step 2.5 for help).
Once bundle has install the gem, you can start the jekyll server by running jekyll serve and navigate to 127.0.0.1:4000/tutorials/awesome-tutorial.htmlin your browser (see step 4 for help) to see your resulting website!
Testing
On your tutorial page, right click and view the page source.
If all is well, you should see your schema.org JSON-LD data inside the HTML. To test whether this is formatted correctly, you can then go to Google structured data testing tool and copy the HTML in.
Once you have created a website that is publicly available online and is correctly formatted with JSON-LD, you can go to the Google Search Console and see more statistics about what and how Google has indexed the metadata on your site.
In the Search Console you can request re-indexing when your schema.org is setup, view the error rates, and see how people are finding and using your site.
Making better use of the metadata
If anything about your training material changes (add a new author, rename it etc), you would have to change both the content and the Front Matter. But one of the advantages of structuring data into a machine readable format is data becomes very accessible and re-usable.
So instead of duplicating information, we should use the metadata to form the view that website users see. Go back to _layouts/tutorial.html and add some more template code to render the metadata variables within the HTML.
Last updated
