--- title: Setup a HUGO Site date: 2022-12-31T22:03:52Z author: "ahmza" draft: false weight: tags: ["blog","website","web development","HUGO"] description: "Always wanted to setup a static website. Look no further !! In this post we go over the basics of setting up a HUGO site" canonicalURL: "https://blog.ahmza.com/Page%28/posts/setting-up-a-hugo-site.md%29" cover: image: "/img/hugo/feature.webp" # image path/url alt: "HUGO Logo" # alt text caption: "The HUGO logo" # display caption under cover relative: false # when using page bundles set this to true --- ## **Introduction** Hugo is a static site generator, a tool that allows us to pre-compile our website into static HTML, CSS and JS. The main benefit of using such methods is speed. A Static site takes a lot less time to load than a site that uses databases. For more information on HUGO read my other post [Hugo Static Site Generator](https://blog.ahmza.com/posts/hugo-static-site-generator/) ## **Prerequisites** - Git ## **Installing HUGO** [Official steps](https://gohugo.io/installation/) The HUGO binary is what we will use throughout the creation of our project to initially setup our site then create posts etc... This step will vary depending on your operating system and distribution. I will show the steps for MacOS and Arch based Linux distros. ### MacOS - Install [homebrew](https://brew.sh/) ``` bash brew install hugo ``` ### Arch ``` bash sudo pacman -S hugo ``` ### Confirm Installation ``` bash hugo version ``` ## Create your site This assumes a few steps for you, i.e the theme used. The settings in this guide will mimic the base config of my site ``` bash hugo new site -f yml cd git init git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod echo "theme: 'PaperMod'" >> config.yml ``` ## Create Content We will now begin adding new content to our website. Lets create our first post. Lets start by creating a template for our posts. ``` bash vim archetypes/posts.md ``` Paste the following base template ``` markdown --- title: {{ replace .TranslationBaseName "-" " " | title }} date: {{ .Date }} author: "" draft: true weight: tags: [""] description: "" canonicalURL: "{{ .Page | absURL }}" cover: image: "" # image path/url alt: "" # alt text caption: "" # display caption under cover relative: false # when using page bundles set this to true --- ## **Introduction** ## **Conclusion** ``` If the posts folder does not exist, create it ``` bash mkdir content/posts ``` Create and edit a post ``` bash hugo new posts/.md vim content/posts/.md ``` ## Start the server Now that we have created our site, installed a theme and created a post lets start the server. ``` bash hugo server -D ``` *The -D flag tells hugo server to build drafts. (notice how we have a draft: option in our posts template.)* *Of course once you have finished a post you set draft to false like so draft: false* You will be shown something like the following: ``` ➜ hugo server -D Start building sites … hugo v0.109.0+extended darwin/arm64 BuildDate=unknown | EN -------------------+----- Pages | 10 Paginator pages | 0 Non-page files | 0 Static files | 0 Processed images | 0 Aliases | 2 Sitemaps | 1 Cleaned | 0 Built in 12 ms Watching for changes in /home/ahmza/prj/ahmza/{archetypes,assets,content,data,layouts,static,themes} Watching for config changes in /home/ahmza/prj/ahmza/config.yml Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop ``` *Notice the second line to the bottom. Web Server... This line gives you a localhost url that you can use in your browser to view your site locally.* ## Configure Site Open the config.yml file in a text editor. ``` bash vim config.yml ``` **Important changes you need to make** - baseURL - this is the URL your site will be accessed externally. In my case. https://blog.ahmza.com - title - is the title of your page. Here is my config.yml with bits redacted so you can fill them in ``` yaml baseURL: "" title: paginate: 5 theme: PaperMod enableRobotsTXT: true buildDrafts: false buildFuture: false buildExpired: false enableEmoji: true googleAnalytics: minify: disableXML: true minifyOutput: true outputs: home: - HTML - RSS - JSON params: env: production # to enable google analytics, opengraph, twitter-cards and schema. title: description: "<description>" keywords: [Blog, Portfolio, PaperMod] author: <author> images: ["<link or path of image for opengraph, twitter-cards>"] #Change this DateFormat: "January 2, 2006" defaultTheme: auto # dark, light disableThemeToggle: false ShowReadingTime: true ShowShareButtons: false ShowPostNavLinks: false ShowBreadCrumbs: true ShowCodeCopyButtons: true ShowWordCount: true ShowRssButtonInSectionTermList: true UseHugoToc: false disableSpecial1stPost: false disableScrollToTop: false comments: false hidemeta: false hideSummary: false showtoc: true tocopen: false assets: # disableHLJS: true # to disable highlight.js # disableFingerprinting: true favicon: "/img/favicon.png" favicon16x16: "/img/favicon.png" favicon32x32: "/img/favicon.png" apple_touch_icon: "/img/favicon.png" safari_pinned_tab: "/img/favicon.png" label: text: "<Home>" icon: /img/favicon.png iconHeight: 35 # profile-mode profileMode: enabled: true # needs to be explicitly set title: "Welcome \U0001F44B" subtitle: "<subtitle>" imageUrl: "/img/favicon.png" imageWidth: 120 imageHeight: 120 imageTitle: "my image" buttons: - name: posts url: posts - name: archive url: archives - name: tags url: tags # home-info mode homeInfoParams: Title: "Welcome \U0001F44B" Content: "subtitle" socialIcons: - name: LinkedIn url: "https://linkedin.com/in/" - name: gitlab url: "https://gitlab.com/" cover: hidden: false # hide everywhere but not in structured data hiddenInList: false # hide on list pages and home hiddenInSingle: false # hide on single page editPost: URL: "https://gitlab.com/<user>/<repo>/-/blob/main/content" Text: "Suggest Changes" # edit text appendFilePath: true # to append file path to Edit link # for search # https://fusejs.io/api/options.html fuseOpts: isCaseSensitive: false shouldSort: true location: 0 distance: 1000 threshold: 0.4 minMatchCharLength: 0 keys: ["title", "permalink", "summary", "content"] menu: main: - identifier: posts name: posts url: /posts/ weight: 1 - identifier: archive name: archive url: /archives/ weight: 10 - identifier: tags name: tags url: /tags/ weight: 20 - identifier: search name: search url: /search/ weight: 30 # Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma pygmentsUseClasses: true markup: highlight: noClasses: false codeFences: true guessSyntax: true # lineNos: true ``` ## Run the server again Run the server and check out your hard work. Change settings make posts etc. Have fun !! ``` bash hugo server -D ``` ## Publish your site Once you are happy with your site, you may want to publish it to the internet. In the next post [Publishing your HUGO site](https://blog.ahmza.com/posts/publishing-your-hugo-site/) I will cover a basic method of publishing your site as well as a more complicated but automated workflow that I use. ## **Conclusion** Through this post you have learned to create your own HUGO site as well as create and edit posts. We also learned about - archetypes - Mark posts as drafts (expand on this - The hugo built in server (still need to add this)) - webp + webm (still need to add this) - shortcodes (still need to add this)