eric/bridget
1
0
Fork 0
mirror of https://github.com/Sped0n/bridget.git synced 2026-04-14 10:09:31 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure documentation

Browse Source 
Signed-off-by: Sped0n <hi@sped0n.com>
This commit is contained in:
Sped0n
2025-11-12 02:23:49 +08:00
committed by Ryan
parent 6be1a924de
commit 48eaa9d95b
5 changed files with 336 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@@ -2,19 +2,27 @@
![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/Sped0n/bridget/build.yml?logo=github) ![GitHub deployments](https://img.shields.io/github/deployments/Sped0n/bridget/Production?logo=vercel&label=deploy)
Bridget is a minimal [Hugo](https://gohugo.io) theme for photographers/visual artists, powered by [Solid.js](https://www.solidjs.com).
Bridget is a minimal [Hugo](https://gohugo.io) theme for photographers/visual artists, powered by [Solid.js](https://www.solidjs.com). Based on the https://github.com/tylermcrobert/bridget-pictures-www.
Based on the https://github.com/tylermcrobert/bridget-pictures-www.
Here is a [live demo](https://bridget-demo.sped0n.com).
![thumbnail](https://raw.githubusercontent.com/Sped0n/bridget/main/images/tn.jpg)
## [Demo Site](https://bridget-demo.sped0n.com)
To see this theme in action, here is a live [demo site](https://bridget-demo.sped0n.com) which is rendered with **Bridget** theme.
> [!NOTE]
> This repository is currently in **maintaince mode** for two reasons:
>
> 1. I want to keep this theme minimal.
> 2. My bandwith after work is limited.
>
> BUT, bug fixes will be addressed (including related issues and PRs), and they are the **number one priority** for this project.
>
> Please understand that feature request might **NOT** be addressed or may take a long time to be implemented.
>
> Anyway, forks are welcomed, and I'm looking forward to seeing what you can do with the theme.
## Getting Started
Head to this [documentation](https://github.com/Sped0n/bridget/blob/main/doc/getStarted.md) for a complete guidance to get started with the Bridget theme.
Head to this [documentation](https://github.com/Sped0n/bridget/blob/main/docs.md) for a complete guidance to get started with the theme.
## Features

196
doc/getStarted.md
View File

@@ -1,196 +0,0 @@
# 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](https://gohugo.io/getting-started/installing/).
Once you have installed Hugo, you can check the version by running the following command:
```shell
hugo version
```
Which should output something like this (the version number may be different), notice the `extended` keyword:
```shell
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`](https://github.com/Sped0n/bridget/blob/main/theme.toml#L19).
## 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:
```shell
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:
```shell
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](https://gohugo.io/hugo-modules/). 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):
```shell
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.
```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
```
> ⚠️⚠️⚠️
>
> 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:
```markdown
---
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`](https://github.com/Sped0n/bridget/blob/main/assets/scss/_partial/_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.
```toml
# theme as module
[module]
replacements = "github.com/Sped0n/bridget/v2 -> ../.."
[[module.imports]]
path = "github.com/Sped0n/bridget/v2"
```
- If you have _installation with Git_
- `replacement`: replace the _path after the arrow_(`../..`) with the location of your local theme file (⚠️⚠️⚠️**relative path to hugo site theme directory only([official doc](https://gohugo.io/hugo-modules/configuration/#module-configuration-top-level))**, example: `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.
### `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**.
>
> You can use any package manager you want (npm/pnpm/yarn/bun).
- run `pnpm install` to install neceessary dependencies.
- run `pnpm run dev` to host a dev server.
- when you’re ready, run `pnpm run build` to update artifacts.

301
docs.md Normal file
View 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>
```

39
exampleSite/config/_default/params.toml
View File

@@ -1,6 +1,23 @@
# --- REQUIRED -----------------------------------------------------------------
# description of the site (will be placed in meta)
description = "Bridget is a minimal Hugo theme designed for photographers/visual artists."
# resize options for dynamic resolution, please refer to https://gohugo.io/content-management/image-processing/#image-processing-options
loResOpt = "800x webp Lanczos q60"
hiResOpt = "2500x webp Lanczos q75"
# labels (text shown on the UI)
[labels]
next = "next"
prev = "prev"
close = "close"
threshold = "Threshold"
error = "page not found"
loading = "loading..."
# --- OPTIONAL -----------------------------------------------------------------
# whether to use favicon resource links
# generate these with https://realfavicongenerator.net
favicon = true
@@ -9,15 +26,6 @@ svgFavicon = "/dot.svg"
# fallback png favicon for unsupported browsers
svgFaviconFallback = "/dot.png"
# resize options for dynamic resolution, please refer to https://gohugo.io/content-management/image-processing/#image-processing-options
loResOpt = "800x webp Lanczos q60"
hiResOpt = "2500x webp Lanczos q75"
# page config
[page]
# unified alt text for all images in the page
unifiedAlt = ''
# site verification code for Google/Bing/Yandex/Pinterest/Baidu
[verification]
google = ""
@@ -61,17 +69,8 @@ token = ""
[analytics.splitbee]
enable = false
# no cookie mode
No_cookie = true
no_cookie = true
# respect the do not track setting of the browser
Do_not_track = true
do_not_track = true
# token(optional), more info on https://splitbee.io/docs/embed-the-script
data_token = ""
# labels
[labels]
next = "next"
prev = "prev"
close = "close"
threshold = "Threshold"
error = "page not found"
other = "loading..."

4
layouts/partials/plugin/analytics.html
View File

@@ -65,10 +65,10 @@
{{- /* Splitbee Analytics */ -}}
{{- if $analytics.splitbee.enable -}}
{{- $attr := "" -}}
{{- if $analytics.splitbee.Do_not_track -}}
{{- if $analytics.splitbee.do_not_track -}}
{{- $attr = printf `%v data-respect-dnt` $attr -}}
{{- end -}}
{{- if $analytics.splitbee.No_cookie -}}
{{- if $analytics.splitbee.no_cookie -}}
{{- $attr = printf `%v data-no-cookie` $attr -}}
{{- end -}}
{{- with $analytics.splitbee.data_token -}}