Visual Studio Code is a lightweight cross platform code editor which provides syntax highlighting, debugging and intellisense support for various programming languages. When I heard about it my initial thought was “Great another editor”. It turned out to be great for Node.js editing because of its awesome Node.js debugger. But I won’t go into that in this post.
One thing you might not know about Visual Studio Code is its great markdown editor and preview feature. For people who use static site generators or write articles in markdown, Visual Studio Code offers a great one stop shop for writing and previewing static content and markup. The built in source control support also allows you to save your content, code and other site assets to a git repository.
Let us walk through creating a static site using Go Hugo (Static Site Generator) and Visual Studio Code.
Please follow the instructions for installing Go Hugo here. If you are on a Mac then it can use homebrew to install it.
shell> brew install hugo
Please follow the instructions for installing Visual Studio Code here.
Creating the Project
Create your static site using the hugo new site command and initialize git for source control.
shell> hugo new site ~/staticsite
shell> cd ~/staticsite
shell> git init
shell> git add .
The staticsite folder should now contain a stub for your new site and git repository. The git add command will allow git to track the files initially generated by the hugo.
Opening the project in Visual Studio Code
While still in the staticsite folder run the following command to open the project in Visual Studio Code.
shell> code .
Visual studio code should open to reveal a screen similar to the following screenshot.
Adding a new content file
Back in the command shell (hoping maybe I or someone will figure out a way to add hugo commands to visual studio code). Run the following command to create your first page.
shell> hugo new /vscode-articles/creating-static-sites.md
The above command will create a folder called vscode-articles in the content folder then create a file called creating-static-sites.md in that folder. Your visual studio code window should look similar to the following screenshot.
Open the newly created content file to begin editing it. The file will contain some meta data commonly referred to as front matter in the static site world. The data in the front matter is used to customize the content generation process. You can begin writing your content below the front matter.
Paste in some markdown content then open up the split editor. Once the split editor is open click on the open preview button for one of the windows. One of your windows will have your content and the other will have your markdown preview. Your window should look similar to the following screenshot.
For those who are wondering, the split editor and preview buttons are to the top right of the editor window. The great thing about the split editor is the preview window updates as you type.
Adding images to your content can be a bit tricky if you don’t use a cdn or external url. Hugo was originally designed to have all static content including images in the static folder. The content of the static folder is copied to the root of your published site. The problem with that approach is markdown preview will not be able to find your images since. I also prefer to store my images together with related content. So great care must be taken when configuring your site because the site url hierarchy is mostly determined by the content folder structure. I have gotten my images to display both in the preview editor and on the generated site by updating the hugo configuration file.
Open config.toml and add the following two options
uglyurls = true
Create a folder called images in the vscode-articles folder and add an image to it. Then, edit your markdown to include the image. Your window should appear similar to the following screenshot where the preview window also displays the image.
This method will only display content images that are rendered on single pages. It will not work on list pages. So if you don’t mind not seeing your images in markdown preview then you can add your images to the static folder and link to them relative to the root of the site.
![VS Code Static Site](/images/staticsite.png)
Preview the Entire Static Site
Before you render the site you must add a theme. Think of the theme as a master template for your pages. It will contain the headers, footers, links to static assets such as css and other customizations for the site. There are quite a few hugo templates in the wild so you can run this command which will download a list curated by the hugo author.
shell> git clone --recursive https://github.com/spf13/hugoThemes themes
Hugo comes with a development server that allows you to preview your site locally before it is published. To test your new static site run the following command
shell> hugo server --theme=hyde --buildDrafts
The above command will generate the site and print out the url of the development server. If you visit the url http://localhost:1313/vscode-articles/creating-static-sites.html you should see something similar to the following screenshot.
When you are ready to publish your content you will set draft to false in the front matter of your content file then generate the site using the hugo command.
0 draft content
0 future content
1 pages created
0 paginator pages created
0 tags created
0 categories created
in 52 ms
Once the site is generated you can upload the contents of the public folder to your host. My static site is hosted on azure websites so I copy the public folder to dropbox and sync dropbox with my azure website to perform updates. You could always use a ci server to watch your git repo and update your site after git commits.