Using Visual Studio Code to Write Articles and Static Sites


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.

Installation

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.

staticsite

The content folder is the designated location for your markdown files. The static folder is reserved for static assets such as your javascript and css. It is important to understand that the files in these folders are not what is uploaded to the webserver. When you generate your static site, it will process  and copy the generated content along with static assets to the public folder. The public folder will be created the first time you generate the site. To understand more about using hugo to generate static sites I encourage you to view their documentation.

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.

staticsite add content

Editing Content

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.

article-with-preview

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

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.

article-with-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.

preview site

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.


shell> hugo
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.