From 48eaa9d95bd2390463958a83051421c3fb32c462 Mon Sep 17 00:00:00 2001 From: Sped0n Date: Wed, 12 Nov 2025 02:23:49 +0800 Subject: [PATCH] docs: restructure documentation Signed-off-by: Sped0n --- README.md | 20 +- doc/getStarted.md | 196 --------------- docs.md | 301 ++++++++++++++++++++++++ exampleSite/config/_default/params.toml | 39 ++- layouts/partials/plugin/analytics.html | 4 +- 5 files changed, 336 insertions(+), 224 deletions(-) delete mode 100644 doc/getStarted.md create mode 100644 docs.md diff --git a/README.md b/README.md index b6618c0..f0d7ef0 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/getStarted.md b/doc/getStarted.md deleted file mode 100644 index 08ceaea..0000000 --- a/doc/getStarted.md +++ /dev/null @@ -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. diff --git a/docs.md b/docs.md new file mode 100644 index 0000000..99f5744 --- /dev/null +++ b/docs.md @@ -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 + + + + /* ---------- INSERT HERE ---------- */ + + +
/* ---------- OR HERE ---------- */
+ + +``` diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml index ecd278b..85a4966 100644 --- a/exampleSite/config/_default/params.toml +++ b/exampleSite/config/_default/params.toml @@ -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..." diff --git a/layouts/partials/plugin/analytics.html b/layouts/partials/plugin/analytics.html index 9c120e5..1adf35c 100644 --- a/layouts/partials/plugin/analytics.html +++ b/layouts/partials/plugin/analytics.html @@ -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 -}}