mirror of
https://github.com/Sped0n/bridget.git
synced 2026-04-18 12:09:29 -07:00
Sped0n
301
docs.md
Normal file
301
docs.md
Normal file
@@ -0,0 +1,301 @@
|
||||
### Contents
|
||||
|
||||
- [Prequisites](#prequisites)
|
||||
- [Installation](#installation)
|
||||
- [Hugo Modules (Recommended)](#hugo-modules-recommended)
|
||||
- [Git Repository (For Customizations)](#git-repository-for-customizations)
|
||||
- [Content Management](#content-management)
|
||||
- [`index.md`](#indexmd)
|
||||
- [Front Matter](#front-matter)
|
||||
- [Markdown Content](#markdown-content)
|
||||
- [Favicon](#favicon)
|
||||
- [Configuration](#configuration)
|
||||
- [`hugo.toml`](#hugotoml)
|
||||
- [`markup.toml`](#markuptoml)
|
||||
- [`outputs.toml`](#outputstoml)
|
||||
- [`params.toml`](#paramstoml)
|
||||
- [`sitemap.toml`](#sitemaptoml)
|
||||
- [Customizations](#customizations)
|
||||
- [Change Font](#change-font)
|
||||
- [Add a Custom Analytic Script](#add-a-custom-analytic-script)
|
||||
|
||||
---
|
||||
|
||||
## Prequisites
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
- Hugo (extended), minimum required version can be seen in the [`theme.toml`](https://github.com/Sped0n/bridget/blob/main/theme.toml#L19)
|
||||
|
||||
```bash
|
||||
❯ hugo version
|
||||
hugo v0.152.2+extended+withdeploy darwin/arm64 BuildDate=unknown VendorInfo=nixpkgs
|
||||
```
|
||||
|
||||
- [Dart Sass](https://gohugo.io/functions/css/sass/#dart-sass) (**DO NOT INSTALL IT FROM NPM**, since it is doesn't support `--embedded`)
|
||||
|
||||
```bash
|
||||
❯ sass --embedded --version
|
||||
{
|
||||
"protocolVersion": "2.4.0",
|
||||
"compilerVersion": "1.70.0",
|
||||
"implementationVersion": "1.70.0",
|
||||
"implementationName": "dart-sass",
|
||||
"id": 0
|
||||
}
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
### Hugo Modules (Recommended)
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Checkout https://gohugo.io/hugo-modules/use-modules/#prerequisite before using Hugo Modules.
|
||||
|
||||
First turn your site into a Hugo module (in case you haven't done it yet):
|
||||
|
||||
```bash
|
||||
hugo mod init github.com/me/my-new-site
|
||||
# or whatever you like, it doesn’t need to be a valid 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.
|
||||
|
||||
```toml
|
||||
# config/_default/hugo.toml
|
||||
[module]
|
||||
[[module.imports]]
|
||||
path = "github.com/Sped0n/bridget/v2"
|
||||
```
|
||||
|
||||
If you want to upgrade the theme, just run:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
### Git Repository (For Customizations)
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
First clone the repository into your `themes` directory:
|
||||
|
||||
```bash
|
||||
# latest version (main branch, might be unstable)
|
||||
git clone https://github.com/Sped0n/bridget themes/bridget
|
||||
|
||||
# and you can checkout to a specific stable version, see https://github.com/Sped0n/bridget/releases
|
||||
cd themes/bridget
|
||||
git checkout v1.0.0
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
git submodule add https://github.com/Sped0n/bridget themes/bridget
|
||||
```
|
||||
|
||||
## Content Management
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### `index.md`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
#### Front Matter
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
Inside each index.md file, there is a front matter like this:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: _default # just copy
|
||||
layout: single # just copy
|
||||
url: /erwitt/
|
||||
menu:
|
||||
main:
|
||||
weight: 3
|
||||
identifier: Erwitt
|
||||
title: Erwitt
|
||||
unifiedAlt: '© Elliott Erwitt'
|
||||
build:
|
||||
publishResources: false # just copy
|
||||
---
|
||||
```
|
||||
|
||||
- `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;
|
||||
|
||||
#### Markdown Content
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
- If this is a **showcase** page:
|
||||
- No need to write anything in index.md.
|
||||
- Place the images in the same directory as `index.md`.
|
||||
- If this is an **information** page:
|
||||
- You can write anything in index.md, and it will be rendered as HTML.
|
||||
- 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`](https://github.com/Sped0n/bridget/blob/main/assets/scss/_partial/_article.scss).
|
||||
|
||||
### Favicon
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
As for the **website icon**, place the files under `static` directory and then go to [config](#configuration) part for further reading.
|
||||
|
||||
## Configuration
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
You can simply copy `exampleSite/config` to the root directory, with some minor modifications and you should be good to go.
|
||||
|
||||
```
|
||||
.
|
||||
└── config
|
||||
└── _default
|
||||
├── hugo.toml
|
||||
├── markup.toml
|
||||
├── outputs.toml
|
||||
├── params.toml
|
||||
└── sitemap.toml
|
||||
```
|
||||
|
||||
### `hugo.toml`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
First, what you need to modify is the `baseURL` and `title`:
|
||||
|
||||
```toml
|
||||
# timeout
|
||||
timeout = "1200s"
|
||||
# your website url
|
||||
baseURL = 'https://bridget-demo.sped0n.com' # <-- MODIFY ME
|
||||
# website title
|
||||
title = 'Bridget' # <-- MODIFY ME
|
||||
# don't touch this
|
||||
disableKinds = ["section", "taxonomy", "term", "home"]
|
||||
# robots.txt
|
||||
enableRobotsTXT = true
|
||||
```
|
||||
|
||||
Depend on which [installation](#installation) method you choose, you need to modify the `module` section:
|
||||
|
||||
- If you use [Hugo Modules](#hugo-modules-recommended):
|
||||
|
||||
```toml
|
||||
[module]
|
||||
[[module.imports]]
|
||||
path = "github.com/Sped0n/bridget/v2"
|
||||
```
|
||||
|
||||
- If you use [Git Repository](#git-repository-for-customizations):
|
||||
|
||||
```toml
|
||||
[module]
|
||||
# This is the relative path to hugo theme directory([official doc](https://gohugo.io/hugo-modules/configuration/#module-configuration-top-level))**.
|
||||
replacements = "github.com/Sped0n/bridget/v2 -> ../.."
|
||||
[[module.imports]]
|
||||
path = "github.com/Sped0n/bridget/v2"
|
||||
```
|
||||
|
||||
### `markup.toml`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
**Just copy it.**
|
||||
|
||||
### `outputs.toml`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
**Just copy it.**
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
### `params.toml`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
Detailed description in the comments.
|
||||
|
||||
### `sitemap.toml`
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
https://gohugo.io/templates/sitemap-template/#configuration
|
||||
|
||||
## Customizations
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please make sure you have [installation with Git](#git-repository-for-customizations).
|
||||
>
|
||||
> - Use `pnpm install` to install neceessary dependencies.
|
||||
> - Use `pnpm run dev` to start a dev server (`http://localhost:1313`).
|
||||
> - When you’re ready, run `pnpm run build` to update artifacts.
|
||||
|
||||
### Change Font
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
These are the places you need to focus on:
|
||||
|
||||
- `assets/scss/_core/_font.scss` (`@font-face`)
|
||||
- `assets/scss/_core/_typography.scss` (`body.font-family`)
|
||||
- `layouts/partials/head/link.html` (`preload`)
|
||||
- `static/lib/fonts/GeistVF.woff2` (font file itself)
|
||||
|
||||
### Add a Custom Analytic Script
|
||||
|
||||
_[Contents](#contents)_
|
||||
|
||||
Go to `layouts/_default/baseof.html`:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="{{- site.LanguageCode -}}">
|
||||
<head>
|
||||
/* ---------- INSERT HERE ---------- */
|
||||
</head>
|
||||
<body lang="{{- site.LanguageCode -}}">
|
||||
<div class="analytics">/* ---------- OR HERE ---------- */</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
Reference in New Issue
Block a user