Building a Jekyll website using Visual Studio

Madhavan Lakshminarayanan — Sun, 03 Jul 2022 05:24:17 +0000

Jekyll is a popular static site generator that takes Markdown content and renders it through templates to produce static pages, which you can then upload to a hosting service such as GitHub Pages.

I'm someone who likes to use an IDE whenever possible, and if you're a Windows developer like me who happens to have Visual Studio installed, then you've already got an excellent dev environment for Jekyll. A lightweight editor such as Visual Studio Code will work just as well, if not better, but I already had Visual Studio, so that's what I used.

Once you've bootstrapped your Jekyll website (see Jekyll documentation for instructions), simply right-click your website folder in File Explorer and select Open in Visual Studio. Out of the box, you get support for most of the file types you will be dealing with, including HTML/CSS, _config.yml and Gemfile. The two quality-of-life improvements that I made were related to Markdown support and a custom task for launching a local server.

Markdown support

Most of the content in a Jekyll website is typically authored using Markdown, however the built-in Markdown support in Visual Studio is somewhat lacking. This is easily fixed by grabbing the excellent Markdown Editor extension from the Visual Studio Marketplace, which improves syntax highlighting and adds live preview.

Note: VS Code supports these features out of the box, no extension needed.

Custom launch task

Jekyll provides an easy way to test your website locally by running bundle exec jekyll serve. I created a custom launch task for this so I could fire up the server without leaving the IDE. To do this, right-click any file in Solution Explorer and select Configure Tasks. In the tasks.vs.json file that opens up, replace the tasks section with the following:

"tasks": [
    {
      "taskLabel": "Local Server",
      "appliesTo": "*",
      "type": "default",
      "command": "${env.COMSPEC}",
      "args": [
        "bundle exec jekyll serve"
      ]
    }
]

Now, when you right-click any file in Solution Explorer, you should see a Run Local Server option. Clicking this will launch the server and Jekyll logs will go to the Output pane. You can continue editing files in the IDE and Jekyll will automatically pick up any changes. The server will terminate when you close Visual Studio; if you need to do this manually (for example, if you make changes to _config.yml), select Build > Cancel from the menu or use the Ctrl+Break shortcut.

Note: VS Code uses a nearly identical tasks.json file for custom tasks. See the documentation for more details.

Compiling a Direct2D linkable shader using Visual Studio

Madhavan Lakshminarayanan — Sun, 03 Jul 2022 05:08:32 +0000

Effect shader linking is a Direct2D optimization that links multiple shaders together so that they can be rendered in a single pass. If you're writing custom shaders, you want to ensure that they are linking compatible in order to take advantage of this optimization. The official documentation explains how to author and compile such effects, however the default HLSL build in Visual Studio does not provide support for linking-compatible shaders. Instead, you need to configure a custom build step to do this, which is what this post will walk you through.

Step 1: Create a batch script to compile the shader

First, create a batch script in your Visual Studio project that will execute the two-step process to compile a linking-compatible shader, let's call it buildshader.bat:

fxc %1.hlsl /nologo /T lib_4_0 /D D2D_FUNCTION /D D2D_ENTRY=main /Fl %1.fxlib /I %2
fxc %1.hlsl /nologo /T ps_4_0 /D D2D_FULL_SHADER /D D2D_ENTRY=main /E main /setprivate %1.fxlib /Fo:%1.cso /I %2

This is taken straight from the official documentation, except I've introduced a couple of parameters so it can be used as a custom build tool. The first is the input file and the second is the SDK include directory (which is required for the d2d1effecthelpers include that you will be using in your shader). The outputs of this script are a .fxlib file (intermediate file) and a .cso file (final linking-compatible shader output).

Step 2: Configure a custom build tool for the HLSL file

Next, for each HLSL file in your project, open up the property page and make the following changes:

Item Type
Custom Build Tool

Command Line
buildshader "%(Filename)" "$(UM_IncludePath)"

Outputs
%(Filename).fxlib;%(Filename).cso

Additional Dependencies
buildshader.bat

The outputs and additional dependencies let the build system know when to trigger a rebuild of the input file. You can read more about these options in the Visual Studio documentation.