[Hugo](https://gohugo.io/) is a static site generator for [[markdown]] files. ## install Hugo Visit the [installation page](https://gohugo.io/installation/) for latest instructions. I installed with `winget`. ```powershell winget install Hugo.Hugo.Extended ``` The executable `hugo.exe` should be added to your [[PATH]] variable by default, if not add it so you can use it with [[Git Bash]]. Hugo is largely used from the [[command line interface|CLI]]. ## build a site Use the CLI to build a site. Navigate to a folder in which to create a new repo for your site. Run the following commands in Git Bash. ```bash hugo new site <site-name> cd <site-name> ``` Hugo builds a full [directory structure](https://gohugo.io/getting-started/directory-structure/) for the site. ## serve a site ```bash hugo serve -D ``` The `-D` flag publishes draft content. Use the `--navigateToChanged` flag to quickly see edits with LiveReload. > [!Tip] > For compatibility with Obsidian, I changed the default.md file in archetypes to use YAML instead of TOML by changing `+++` to `---`. ## assets Hugo's system for managing CSS and JavaScript can be confusing. Previously, the `static` directory was used for images, CSS and JavaScript. Now, you should use page bundles (for page-specific assets) or [asset pipelines](https://gohugo.io/hugo-pipes/introduction/) (for global assets). > [!Tip] > If you are using a theme, the provided `assets/css/main.css` and `assets/js/main.js` are included by default. I strongly recommend working with layouts and assets inside a theme rather than in the root as you get a lot of pre-defined templates when you create a theme. ### CSS Include global CSS in the `assets` directory and use a [Go Pipe](https://gohugo.io/templates/introduction/#pipes) to access it. For example, with file `./assets/main.css`, add the following to your `layouts/head.html` file (in either the root or the `theme` directory). ```go {{ $style := resources.Get "main.css" | resources.Minify | resources.Fingerprint }} <link rel="stylesheet" href="{{ $style.Permalink }}"> ``` ### JavaScript Similar to CSS, store JavaScript files in the `assets` directory. For a file `./assets/main.js`, add the following to your `layouts/baseof.html` file (in either the root or the `theme` directory). ```go {{ $mainJs := resources.Get "js/main.js" | js.Build "main.js" | minify | fingerprint }} ``` ## data ## drafts A post will not be shown if the draft property is set to true or the date is set in the future. To serve the site with drafts and future posts, use ```bash hugo server --buildDrafts --buildFuture ``` ## themes A theme is basically a carbon copy of the basic site directory with defaults. Anything you add to your site (in the root) will overwrite what is in the theme. For example, any CSS in `./assets/` will overwrite the CSS in `themes/my-theme/assets/`. You don't need a theme, you can simply build up the CSS, JavaScript, layouts, etc. in the relevant subdirectories of the site itself. You might want to instead develop a theme if you want to be able to quickly change the look and feel of your site. To create a new theme use ```bash hugo new theme <theme-name> echo "theme = 'theme-name'" >> hugo.toml ``` ## hugo admonitions The project `hugo-admonitions` supports Obsidian-style admonition syntax. Simply install with (you'll need the project initialized with git first): ```bash git submodule add https://github.com/KKKZOZ/hugo-admonitions.git themes/hugo-admonitions ``` and then add it to your` hugo.toml` configuration file. ```toml [[module.imports]] path = "hugo-admonitions" ``` ## math via LaTeX See the four step instructions [here](https://gohugo.io/content-management/mathematics/) to allow rendering of math equations using [[MathJax]]. For compatibility with Obsidian, make sure to include the ` as an inline delimiter in both the `hugo.toml` site configuration and the `math.html` files. > [!Tip]- Additional Resources > -[Luke Smith | Hugo Actually Explained](https://youtu.be/ZFL09qhKi5I?si=seTAhxL_lI5QnLsx) >