[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 ## 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) >