Creating your first site with Hinode

Posted on April 3, 2023 (Last modified on May 27, 2023) • 9 min read • 1,839 words

guide

vscode

guide

vscode

Share via

Link copied to clipboard

Guide on how to set up your site with version control and automated testing using GitHub and VSCode.

On this page

Creating your first site with Hinode — Photo by SpaceX on Unsplash

Introduction

The commands and code examples within this guide are written with macOS in mind. The commands should be transferrable to Windows and Linux too.

Hinode uses Hugo, a popular open-source generator, to generate a static website. Static websites do not require a database and can be hosted virtually anywhere. In this guide, we will set up a new site using a template from GitHub. We will then edit our Markdown content with Visual Studio Code (VSCode). Lastly, we will submit our changes to the main branch using automated testing.

This guide requires a GitHub account to host the demo repository. Next, Git, Node.js and npm are required for local development and testing. The guide also uses VSCode to edit the content. Click on each of the following links to sign up and install the required software as necessary. The software packages should be compatible with Windows, macOS, and most Linux distributions.

Set up an account with GitHub
Download and install the Git binary
Download and install Node.js (it includes npm)
Download and install VSCode

Step 1 - Initializing the project

As first step we will create a new repository on GitHub using a template. We will then connect our local machine to the remote repository and install the required dependencies. Lastly, we will run a local development server to test the newly created site.

Creating a new Git repository

Hinode comes in two flavors: a template and a main theme. The template uses npm to link to the latest available version of Hinode. We will use the template as starting point for our new site, as it hides away most of the source code of the main theme. Unless you plan to customize a lot, it is recommended to use the template for your future projects.

Step 1. Create a new repository from the template

Step 2. Enter a repository name

Step 3. Review the initialized repository

Navigate to https://github.com/gethinode/template in your browser and click on the green button Use this template to create a new repository. You may need to sign in to GitHub for the button to become available. Provide a meaningful name for your repository, such as hinode-demo. The repository’s visibility can be either private or public. Public repositories can be seen by anyone, such as open-source projects. Private repositories are only visible to yourself, or to anyone you have granted access. Lastly, click on the green button Create repository from template to create your repository.

Connecting your local machine

We will now connect our local machine to the newly created GitHub repository. Navigate to a folder on your local machine, such as ~/Documents. Use the git clone command to download and extract your GitHub repository within the current folder. By default, git creates a new subfolder with the name of your repository, e.g. hinode-demo. The next command is an example, be sure to replace the <USER> name with your own.

git clone https://github.com/<USER>/hinode-demo.git
Cloning into 'hinode-demo'...
remote: Enumerating objects: 62, done.
remote: Counting objects: 100% (62/62), done.
remote: Compressing objects: 100% (43/43), done.
remote: Total 62 (delta 9), reused 49 (delta 8), pack-reused 0
Receiving objects: 100% (62/62), 3.27 MiB | 974.00 KiB/s, done.
Resolving deltas: 100% (9/9), done.

Installing the packages and dependencies

We will now install the various packages and dependencies used by Hinode. The file packages.json in the repository root defines the npm packages and their versions as used by Hinode. First, navigate to the hinode-demo folder:

cd hinode-demo

Next, use the command npm install to download and install the various packages. npm will store these files in the hinode-demo/node_modules folder. The script downloads and installs the latest Hugo binary automatically. In this approach, the Hugo binary is linked exclusively to your repository, minimizing potential version conflicts on your local machine.

npm install

added 528 packages, and audited 529 packages in 8s

153 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Running a local development server

Your site is now ready for testing. Enter the following command to start a local development server:

npm run start
> @gethinode/template@0.7.3 prestart
> npm run clean

> @gethinode/template@0.7.3 clean
> shx rm -rf public resources

> @gethinode/template@0.7.3 start
> hugo server --bind=0.0.0.0 --disableFastRender

Start building sites …
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended darwin/arm64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio

                   | EN  | NL
-------------------+-----+-----
  Pages            |  36 | 35
  Paginator pages  |   0 |  0
  Non-page files   |   0 |  0
  Static files     |  38 | 38
  Processed images | 135 | 12
  Aliases          |   3 |  2
  Sitemaps         |   2 |  1
  Cleaned          |   0 |  0

Built in 32352 ms
Watching for changes in Documents/hinode-demo/{archetypes,assets,content,data,i18n,layouts,node_modules,package.json,static}
Watching for config changes in Documents/hinode-demo/config/_default, Documents/hinode-demo/config/_default/menus
Environment: "development"
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop

It usually takes less than a minute to build the site and to start the web server in development mode. Before building the site, Hinode cleans several folders. The build itself shows the result of the pages and other assets generated by Hugo. By default, the starter web site is bilingual and supports both the English and Dutch language. Lastly, Hugo mentions the local address on which it is available (usually http://localhost:1313/) and indicates the folders it is watching. The latter means that if you make any changes whilst the web server is running, Hugo should pick up those changes and regenerate the applicable assets. Using a feature called live reloading, your web browser will be instructed to refresh the web page accordingly.

Step 2 - Managing the content

We will now use VSCode to modify the content of our demo site. Start the application and open the hinode-demo folder. The explorer view provides an overview of the folders and files of the repository. The key folders are the following:

Folder	Description
`assets`	Contains static files such as images and stylesheets that are processed by Hugo during build.
`config`	Defines the configuration of the site.
`content`	Maintains the content and its translations of the site.
`layouts`	Defines Hugo shortcodes and partials.
`static`	Specifies static files to be deployed as-is, thus without any processing by Hugo.

Step 1. Open the source code folder in VSCode

Step 2. Create a new develop branch

Step 3. Edit the about page

We will now set up a new branch before we make any changes. It is a good software practice to set up at least one branch for development and testing, instead of working directly on the main branch. Hinode provides several predefined tests that verify if submitted changes in a Pull Request adhere to coding conventions and do not break the build.

Head over to the Source Control section of VSCode and click on the button ... to open the source control menu. Within the menu, navigate to Branch / Create Branch.... Provide develop as branch name and confirm with enter. The blue status bar on the bottom of VSCode will now display develop as selected branch. A repository usually contains a main branch that maintains the production code, and one or more development branches. Complex projects with multiple contributors may have multiple active (feature) branches and even nested branches.

Still within the develop branch, replace the content of the content/en/about.md with the following. When done, head over to the address http://localhost:1313/en/about/ in your web browser to validate the result of the changes.

---
title: About
description: The Hinode demo site illustrates how to set up a new web site.
date: 2023-03-29
showComments: false
---

This is my first site created with Hinode.

Step 3 - Validating the changes

Hinode defines severals tests to validate the code adheres to coding standards. Run the following command to run the tests locally. The test should confirm our code is safe to check in.

npm run lint

> @gethinode/template@0.7.3 lint
> npm run -s lint:markdown

markdownlint-cli2 v0.6.0 (markdownlint v0.27.0)
Finding: *.md content/**/*.md !node_modules !CHANGELOG.md
Linting: 27 file(s)
Summary: 0 error(s)

Step 1. Stage the changes

Step 2. Publish the branch

Head over to VSCode’s Source Control to view the pending changes. Click on the file about.md to open the code inspector. VSCode will then show the differences between the previous version and current version of the file. Content that has been replaced or removed is marked red, and content that has been added or modified is marked green. Verify the changes and click on the + button to stage the changes. Enter a descriptive commit message such as Update about page. When done, click on the blue Commit button to commit the changes on the develop branch. Lastly, click on the blue button Publish Branch to submit tbe branch and its content to GitHub. For an existing branch you would push the button Sync Changes instead.

By convention, a commit message should use the imperative mood and should be less than 150 characters in total. Review the blog from Initial Commit to see more best practices and guidelines to write good commit messages.

Step 4 - Submitting a Pull Request

With your changes committed to the remote develop branch, you can now merge the changes with the main branch. Head over to your repository on GitHub to submit a Pull Request (PR). Click on the green button New pull request within the menu Pull Requests to do so. Enter a descriptive title for the PR, or confirm the default title suggested by GitHub. Click on the green button to submit the PR, which triggers GitHub to run several checks. By default, Hinode runs a linting test and builds the web site with the latest three versions of Node.js. The linting test is the same test ran in the previous step. The tests act as a sort of safeguard to prevent changes breaking the main repository. You can confirm the merge when all checks have passed successfully. You can then observe the commit message associated with the content folder when you head back to the code of the main repository.

Step 1. Open a pull request

Step 2. Enter a descriptive title

Step 3. Run the checks

Step 4. Validate all checks have passed

Step 5. Confirm the merge

Step 6. Review the merge completion

Step 7. Observe the committed changes

Conclusion

You have now successfully created your initial Hinode site with version control and automated testing. Review the hosting and deployment options to see various options on how to publish your site to a hosting provider. While you continue to make updates to the content and layout of your site, you should consider to regularly update the dependencies of your repository too. Use the upgrade command to check for any package updates. If applicable, run npm install again to install the updated packages.

npm run upgrade

> @gethinode/template@0.7.3 upgrade
> npx npm-check-updates -u

Upgrading Documents/hinode-demo/package.json
[====================] 18/18 100%

All dependencies match the latest package versions :)

You can also enable Dependabot on your GitHub repository to automatically keep the dependencies and packages used in your repository updated to the latest version.

Adding npm packages

On this page