From a1be94a4126e3c47ee1f9ef9d682fb9c50700ee4 Mon Sep 17 00:00:00 2001 From: Hamza Ahmed Date: Sat, 31 Dec 2022 23:57:20 +0000 Subject: [PATCH] added a new post, setup-a-hugo-site.md --- archetypes/posts.md | 5 +- ...rator.md => hugo-static-site-generator.md} | 6 +- content/posts/setup-a-hugo-site.md | 326 ++++++++++++++++++ 3 files changed, 333 insertions(+), 4 deletions(-) rename content/posts/{hugo-site-generator.md => hugo-static-site-generator.md} (93%) create mode 100644 content/posts/setup-a-hugo-site.md diff --git a/archetypes/posts.md b/archetypes/posts.md index 2de26ba..94da7f0 100644 --- a/archetypes/posts.md +++ b/archetypes/posts.md @@ -15,5 +15,8 @@ cover: caption: "" # display caption under cover relative: false # when using page bundles set this to true -searchHidden: false --- + +## **Introduction** + +## **Conclusion** diff --git a/content/posts/hugo-site-generator.md b/content/posts/hugo-static-site-generator.md similarity index 93% rename from content/posts/hugo-site-generator.md rename to content/posts/hugo-static-site-generator.md index 6042fca..931a8e5 100644 --- a/content/posts/hugo-site-generator.md +++ b/content/posts/hugo-static-site-generator.md @@ -7,7 +7,7 @@ weight: tags: ["blog","website","web development","HUGO"] description: "HUGO is a static site generator. No idea what that is ? Check out this post to learn more !" -canonicalURL: "https://blog.ahmza.com/Page%28/posts/hugo-site-generator.md%29" +canonicalURL: "https://blog.ahmza.com/Page%28/posts/hugo-static-site-generator.md%29" cover: image: "/img/hugo/feature.webp" # image path/url @@ -37,7 +37,7 @@ Some of the disadvantages I have come across are as follows: in my infrastructure!!** Deploying the site in my environment was a challenge as I had to get the site files from gitlab and build a docker image that would compile the site as well as create an image to be -deployed in my [docker swarm.](https://blog.ahmza.com/Page%28/posts/building-a-docker-swarm-with-pis.md%29) +deployed in my [docker swarm.](https://blog.ahmza.com/posts/building-a-docker-swarm-with-pis) I do feel I made this more complicated than it needed to be, however now that I have it working the workflow is great. @@ -113,4 +113,4 @@ page refreshes so you can see changes without manually refreshing. This post is a quick intro to HUGO and why I choose to use it, However there is another post on setting up a HUGO site from start to finish. -[Setting Up a HUGO Site](https://blog.ahmza.com/Page%28/posts/setting-up-a-hugo-site.md%29) +[Setting Up a HUGO Site](https://blog.ahmza.com/posts/setup-a-hugo-site) diff --git a/content/posts/setup-a-hugo-site.md b/content/posts/setup-a-hugo-site.md new file mode 100644 index 0000000..1cb006a --- /dev/null +++ b/content/posts/setup-a-hugo-site.md @@ -0,0 +1,326 @@ +--- +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)