Let's Start Building
This is your one stop guide to creating a new HTML page, from opening a new repository, using a template or linking in our JWS stylesheet, to making a skeleton page using the built in emmet snippets.
What is Emmet?
Emmet is a built-in feature within VS Code plus a large number of other editors and services, that provides predefined snippets for a number of languages.
These snippets can really speed up your workflow, once you get used to using them. Everyone likes less typing right?!!
Using Emmet
You enter the Emmet snippet within your HTML or CSS file then press Tab to expand the snippet. If you enter the snippet and don't see the option menu press Ctrl + Spacebar then you will be able to press Tab You can also use the Ctrl + Spacebar twice to see a sample of the expanded snippet pressing Ctrl + Spacebar again will close the sample popup.
We have a short overview of Emmet available that covers some of the Emmet abbreviation you can use.
Saving locally - Just want to use a code editor and save your files locally, no problem you can skip straight to the New HTML file section below and start following along.
Create a new Repository
Firstly lets make sure we are logged into GitHub
We have two choices whilst creating the repository we can use a template or start with an empty repository the choice is yours (we provide outlines for both options)
If you chose the template option you will have access to the stylesheet and VS code Snippets. If you start with an empty repository you can manually add these files.
Using a Template
To start with the templates head to the JWS One or JWS Two repository page
Click on the Use this template
Choose Create a new repository
then fill out the details
Once your repository is created, we can start to build the HTML pages to do this we need to open an editor, we are going to use the GitHub web editor which we cover in the section below titled New HTML File
New Repository
To start a new repository on your GitHub page choose New then fill out the Create a new repository form.
Now add a new Repository name.
Then choose if you want it to be Public or Private
Now comes the Important checkbox
Initialize this repository with: Add a README file
You could also choose to:
Add .gitignore
Choose a license
but you don't need to to follow along.
Adding a README means that we will be able to use the GitHub web editor to work with this repository, If you don't add one then you would need to use GitHub Codespaces or remote tooling to add files to the new repository.
So now you are set to start working on your HTML pages lets open the GitHub web editor to continue which we cover in the section below titled New HTML File
Install CodeSwing
Whilst using github.dev if you want to be able to see the changes you are making in real time alongside your code? Then we suggest installing the VS Code addin CodeSwing. You can find our how to guide to Installing CodeSwing in our docs.
We also have some additional faq's for using CodeSwing which you can find here on our docs Frequently Asked Questions, Info & Tips page
Adding the JWS files manually
To use the JWS CSS file then you could manually add it by heading to the JWS One repository page click on the file you are interested in once its open for you to view the content click on the raw button to open a plain text version of the file
Now you can click on the page and select all the text Ctrl + A then copy it using Ctrl + C in your GitHub web editor create the file you want in your repository and open it then you can paste the copied text in using Ctrl + V
New HTML File
In your GitHub repository, lets open the github.dev web editor by pressing the . period/full stop key this will open github.dev web-based editor in your current browser tab. However you can also open it in new tab press Shift ↑ + > Note: You need to be logged into GitHub.com to use github.dev web editor.
Working locally: Open your chosen editor.
Now that your web editor or editor is open, there are two ways we can create a new file:
Create a Folder/File First
Open the hamburger menu 
at the top of the activity bar.
There select from the options File then New File...
A "New File" text box will now appear, here we will create your new file inside a named folder.
To do this we first type a slash / followed by the name of your new folder, this will be the name of your page ( e.g. /about )
This is followed with another slash / the file name index and the file type .html (e.g. /about/index.html ) then press Enter
The box title will now change to say "Create File" and you will need to select the Ok box from the two blue boxes on the right.
The box will then prompt with this question "This folder [your chosen name] does not exist. Would you like to create it?" select the blue Ok box again.
Your new folder and HTML file will now open in the editor ready to start creating your new page.
Quick Start a HTML File
Open the hamburger menu at the top of the activity bar.
There select from the options File then New Text File...
A new untitled file tab will open in your editor saying this along the top of the page:
"Select a language (Ctrl + K M), or fill with template, or open a different editor (Ctrl + Alt + Windows + N) to get started."
Click on the Select a language (or Ctrl + K M )
An option box with a list of code languages will appear with an input box. You can either scroll down the list to find your chosen language or start typing in the box until you see the one you want appear on the list, then click on it to select.
We need to select HTML
Your new HTML file will now open in the editor ready to start creating your new page, though you will have to name the file before you can save it. Also remember its always best to be safe than sorry so don't forget to save as soon as you can.
Skeleton HTML Page
On your empty page first type an exclamation mark ! then Tab or Enter and hey presto!
You now have the beginning skeleton of a HTML page, which should look like this:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
</body>
</html>Meta Tags & Links
Title
Now use the Tab key until you reach the page <title> and the word "Document" is highlighted. Then type in a new title appropriate to your page and it's content.
A webpage <title> should typically be between 50 and 60 characters for optimal readability and SEO performance. Too short, and it might not fully convey the page's purpose. Too long, and search engines may truncate it in search results, cutting off important information.
Description, Author & CSS
Next we need to add <meta> tag lines for page "description" and "author", plus a <link> to our "style.css" file. By going to the end of the </title> tag and pressing Enter/Return so you are on a new blank line.
Then add the Emmet snippet: meta:desc+meta[name=author][content=]+link:css
Note as you start to type this command you will see an option box appear you can now either select by clicking on the above snippet command or by continuing to type it in full then press either Tab or Enter
You should find yourself automatically in the content part of the "description" where you need to add your own words, this should be a short summary of the content of the page.
A meta "description" should typically be between 150 and 160 characters to be fully displayed in search engine results. If too short, it might not effectively describe the page’s content. If too long, search engines may truncate it, cutting off important details.
The href="" link to the stylesheet should already say "style.css" you will however need to complete the file path to your downloaded (or cloned) copy of our template CSS file, or you can copy and paste the link to our CDN version from the Templates page.
CDN version: Please note that any changes you wish to make to the base CSS will need to be either added within <style></style> tags, or to your own linked CSS file, either way should be added below the CDN version link within the page <head> section.
HTML Page Body
We now need to complete the skeleton page by adding inside the opening and closing <body> tags, a <header>, <main> & <footer> tag by typing the Emmet snippet: header+main+footer
You are now all ready to start adding in the contents that will be visible to your website users, why not check out our pattern guides for inspiration and help.
Staging and Committing changes
If you are working in a repository using github.dev web editor, its straight forward to stage your changes and then commit them to your repository. We cover the steps in our Build Steps doc's section Staging & Commits if you would like a refresher.
Hosting with GitHub Pages
Once you are happy that the webpage(s) that you are building in your GitHub repository are ready to deploy, you might want to turn on GitHub Pages, so that you can share with others what you have built or just to view it yourself in the browser.
To Turn GitHub Pages on from your repository you can follow the steps we have outlined in our docs page Set up GitHub Pages.
GitHub Pages provides you with a URL and configures an SSL certificate for you, so you don't have to worry about that yourself.
After that you might think about purchasing your own domain name too, we have outlined the steps needed to do this in the docs Domain Names section Registering a Domain Name page.
Once you have registered your domain name you can follow the GitHub's docs page to configure your newly registered custom domain to point to your GitHub Pages site.
Pattern Guides
In our Docs JWS Styling section we have a growing collection of style guides and common page layout patterns. Using both our JWS CSS pre-defined classes and semantic HTML elements.
Page Last Edited: