bridget/doc/getStarted.md

Getting Started

The files in exampleSite is just a simple example. Now, we will introduce it based on the same structure.

Requirements

Before you start, make sure you have installed Hugo extended version. For more information, see Hugo's documentation.

Once you have installed Hugo, you can check the version by running the following command:

hugo version

Which should output something like this (the version number may be different), notice the extended keyword:

hugo v0.120.3-a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970+extended darwin/arm64 BuildDate=2023-11-01T17:57:00Z VendorInfo=brew

The minimum required Hugo version can be seen in the theme.toml.

Installation

Git (for adavanced user)

On the main branch, you can find the theme's latest source code. To use the latest version, you can clone the repository to themes/bridget by running the following command in the root directory of your Hugo site:

git clone https://github.com/Sped0n/bridget themes/bridget

If you are already using Git for your site, you can add the theme as a submodule by running the following command in the root directory of your Hugo site:

git submodule add https://github.com/Sped0n/bridget themes/bridget

⚠️⚠️⚠️

Please refer to the config section for the following content.

Module (recommended)

If you want to have some customizations, use Git installation instead.

This theme is also available as a Hugo module. Run the following command in the root directory of your Hugo site:

First turn your site into a Hugo module (in case you haven't done it yet):

hugo mod init github.com/me/my-new-site
# or whatever you like, it doesn’t necessarily have to be a GitHub repo link.
hugo mod init blablabla

Then import the theme as a dependency adding the following line to the module section of your site's configuration file.

# config/_default/hugo.toml
[module]
[[module.imports]]
path = "github.com/Sped0n/bridget"

If you want to upgrade the theme, just run:

hugo mod get -u

⚠️⚠️⚠️

Please refer to the config section for the following content.

Content Management

The content is where the pictures/text is stored, while the static refers to the website icons.

.
├── content
│  ├── Erwitt
│  │  ├── 1.jpg
│  │  ├── ***
│  │  └── index.md
│  ├── Gruyaert
│  │  ├── 1.jpg
│  │  ├── ***
│  │  └── index.md
│  ├── Info
│  │  └── index.md
│  └── Webb
│     ├── 1.jpg
│     ├── ***
│     └── index.md
└── static
   ├── dot.png
   └── dot.svg

In each index.md file, there is a configuration file like this:

---
type: _default
layout: single
url: /erwitt/
menu:
  main:
    weight: 3
    identifier: Erwitt
    title: Erwitt
unifiedAlt: '© Elliott Erwitt'
_build:
  publishResources: false
---

• keep the type and layout untouched;

• url is the href link to this page, in this case, you can visit this page with blabla.com/erwitt;

• main is the entry to menu;

• weight determines the position of this link in the navigation bar, with the first one being 1, the second one being 2, and so on;

• identifier should be the same as the name of the upper-level directory;

• title refers to the text that appears on the navigation bar;

• unifiedAlt is optional, If you left it empty, the alt attribute of the image will default to its file name; if it is set, the alt attributes of all images will be unified to the value you have set;

• publishResources is optional but recommended, setting it to false will hide unprocessed images in the public directory. By default, Hugo’s value for this option is true, which can potentially result in source image leakage.

• If this is a showcase page, simply place the images in the same directory as index.md.

• If this is an information page, you can continue writing the information you want to display in index.md.

  However, please note that the CSS for the information page only provides simple styling for text. If you have any requirements beyond text and the browser rendering does not meet your expectations, please modify _article.scss.

As for the website icon, place the files in static and then go to config part for further reading.

Config

You can simply copy this to the root directory of your site with minor modifications, and you’ll be ready to proceed.

.
└── config
   └── _default
      ├── hugo.toml
      ├── markup.toml
      ├── params.toml
      └── sitemap.toml

hugo.toml

We will focus on introducing the part about theme as module, detailed comments are provided for other options, so we won’t repeat them here.

# theme as module
[module]
replacements = "github.com/Sped0n/bridget -> ../.."
[[module.imports]]
path = "github.com/Sped0n/bridget"

• If you have installation with Git

  • replacement: replace the path after the arrow(../..) with the location of your local theme file (⚠️⚠️⚠️relative path only, example: themes/bridget)
  • path: no change

• If you have installation with Module, remove the replacements configuration.

markup.toml

DO NOT TOUCH THIS

params.toml

Detailed description in the comments.

⚠️⚠️⚠️

Only thing that you need to pay extra attention is the bundled option, please read the corresponding doc and set it as your need.

For users who have installation with module, please always set this option to true, unless you know what you are doing.

Or you might get the error related to node_modules/swiper/swiper.scss.

sitemap.toml

https://gohugo.io/templates/sitemap-template/#configuration

Customization (AKA for developer)

Before heading to this section, please make sure you have installation with Git.

Option 1: it just works way

If you want to modify js/ts file, please use option 2.

1. Use hugo create a site and move the bridget theme into the theme directory.
2. Run npm install in the bridget theme root dir, not your hugo site root dir.
3. After the command is done, copy the node_modules dir from bridget theme root dir to your hugo site root dir.
4. In your hugo site root dir, write/modify configuration files according to your needs, remember to set bundled option to false, so hugo will not use prebuilt css file.
5. Run hugo server in your hugo site root dir, and you are good to go.

Option 2: recommended way

1. Use hugo create a site and move the bridget theme into the theme directory.
2. Run npm install in the bridget theme root dir, not your hugo site root dir.
3. Run npm run dev in the bridget theme root dir, we will use content in exampleSite to debug.
4. Make your customization.
5. After modification, run npm run build in the bridget theme root dir to build artifacts.
6. In your hugo site root dir, write/modify configuration files according to your needs, remember to set bundled option to true, so hugo will use the artifacts you built in step 5.
7. Run hugo server in your hugo site root dir, and you are good to go.