From 9576b06fda147eee1fdd48b1ab29619617ef27f9 Mon Sep 17 00:00:00 2001 From: "guangzheng.li" Date: Fri, 19 Aug 2022 21:09:07 +0800 Subject: [PATCH] feat: add document --- README.md | 6 +- docs/analytics.md | 30 ++++ docs/comment-system.md | 36 +++++ docs/configurations.md | 316 +++++++++++++++++++++++++++++++++++++++++ docs/home.md | 14 ++ docs/multi-language.md | 88 ++++++++++++ docs/quick-start.md | 15 ++ docs/umami.md | 46 ++++++ 8 files changed, 550 insertions(+), 1 deletion(-) create mode 100644 docs/analytics.md create mode 100644 docs/comment-system.md create mode 100644 docs/configurations.md create mode 100644 docs/home.md create mode 100644 docs/multi-language.md create mode 100644 docs/quick-start.md create mode 100644 docs/umami.md diff --git a/README.md b/README.md index e5615e7..96193b8 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,13 @@ Demo is built up with [exampleSite Source Code](https://github.com/guangzhengli/ --- +## Documentations [`docs`](docs/home.md) + +See [`docs`](docs/home.md) folder. + ## Quick Start -Just click `Use this template` to create your blog site in the [exampleSite Source Code](https://github.com/guangzhengli/hugo-ladder-exampleSite). +Just click `Use this template` to create your blog site in the [exampleSite Repository](https://github.com/guangzhengli/hugo-ladder-exampleSite). Create a new repository(GitHub Pages) from hugo-ladder-exampleSite to enter : `username.github.io`. diff --git a/docs/analytics.md b/docs/analytics.md new file mode 100644 index 0000000..8b38477 --- /dev/null +++ b/docs/analytics.md @@ -0,0 +1,30 @@ +### Analytics + +#### Google Analytics + +Follow [these steps](https://gohugo.io/templates/internal/#configure-google-analytics). + +#### Google Tag Manager + +Follow [these steps](https://developers.google.com/tag-manager). + +```yml +params: + analytics: + google: + SiteVerificationTag: gid +``` + +#### Umami Analytics + +Follow [these steps](https://guangzhengli.com/blog/en/how-to-integrate-umami-for-free-to-blog-site/). + +```yml +params: + analytics: + umami: + enable: true + website_id: data-website-id + url: https://umami-ochre-nu.vercel.app/hugo-ladder.js +``` + diff --git a/docs/comment-system.md b/docs/comment-system.md new file mode 100644 index 0000000..60c0611 --- /dev/null +++ b/docs/comment-system.md @@ -0,0 +1,36 @@ +### Comment Systems + +Comments are displayed within post pages and guestbook. + +#### Giscus + +Follow [these steps](https://giscus.app/). + +```yml +params: + comments: + giscus: + enable: true + repo: username/reponame + repo_id: Rid + category: Announcements + category_id: DIC_id + mapping: pathname + position: top + lang: en # pick a language from https://github.com/giscus/giscus/tree/main/locales +``` + +#### Utterances + +Follow [these steps](https://utteranc.es/) + +```yml +params: + comments: + utteranc: + enable: false + repo: username/reponame + issueTerm: pathname +``` + +## \ No newline at end of file diff --git a/docs/configurations.md b/docs/configurations.md new file mode 100644 index 0000000..aac594c --- /dev/null +++ b/docs/configurations.md @@ -0,0 +1,316 @@ +# Configuration + +## Mini Configuration + +Open the `config.yml` file in the root directory with an editor and change the configuration as follows: + +```yml +baseURL: 'https://hugo-ladder.pages.dev' # set https://username.github.io +homepage: 'https://hugo-ladder.pages.dev' # set https://username.github.io +defaultContentLanguage: 'en' #default language +params: + brand: HOME # set the brand of your site + avatarURL: /images/avatar.png # avatar, replace your avatar in the /static/images/ + author: Hugo Ladder # name + authorDescription: # description + info: this is a info # information of your blog site + favicon: /images/avatar.png # blog site icon，replace your avatar in the /static/images/ + options: + showDarkMode: true # is show dark mode button + enableMultiLang: true # is show multi language button +``` + + +# Configurations + +## About Hugo Configurations + +This theme supports: + +* Analytics + * [Google Analytics](https://developers.google.com/analytics) + * [Google Tag Manager](https://developers.google.com/tag-manager) + * [umami](https://umami.is/) +* Commenting Systems + * [Giscus](https://giscus.app/) + * [Utterances](https://utteranc.es/) + +### Analytics + +#### Google Analytics + +Follow [these steps](https://gohugo.io/templates/internal/#configure-google-analytics). + +#### Google Tag Manager + +Follow [these steps](https://developers.google.com/tag-manager). + +```yml +params: + analytics: + google: + SiteVerificationTag: gid +``` + +#### Umami Analytics + +Follow [these steps](https://guangzhengli.com/blog/en/how-to-integrate-umami-for-free-to-blog-site/). + +```yml +params: + analytics: + umami: + enable: true + website_id: data-website-id + url: https://umami-ochre-nu.vercel.app/hugo-ladder.js +``` + +### Commenting Systems + +Comments are displayed within post pages and guestbook. + +#### Giscus + +Follow [these steps](https://giscus.app/). + +```yml +params: + comments: + giscus: + enable: true + repo: username/reponame + repo_id: Rid + category: Announcements + category_id: DIC_id + mapping: pathname + position: top + lang: en # pick a language from https://github.com/giscus/giscus/tree/main/locales +``` + +#### Utterances +Follow [these steps](https://utteranc.es/) +```yml +params: + comments: + utteranc: + enable: false + repo: username/reponame + issueTerm: pathname +``` + +## Theme Parameters + +These are all the parameters used by `hugo-coder` theme. + +| Name | Type | Required | Description | Default | Example | +| ------------------------------- | ------ | -------- | ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| baseURL | string | Yes | Website URL | | `https://username.github.io` | +| title | string | Yes | Website Name | | `"Ladder"` | +| theme | string | Yes | theme name, not change | `"hugo-theme-ladder"` | `"hugo-theme-ladder"` | +| license | string | No | License | `"MIT"` | `"MIT"` | +| licenselink | string | No | License URL | '"https://github.com/guangzhengli/hugo-theme-ladder/blob/master/LICENSE"' | '"https://github.com/guangzhengli/hugo-theme-ladder/blob/master/LICENSE"' | +| description | string | No | Website Description | | `"'A fast, clean Hugo theme'"` | +| defaultContentLanguage | string | Yes | Website default language | `"en"` | `"en"` or `"zh"` | +| googleAnalytics | string | No | google analytics | `"G-xxx"` | ``"G-xxx"`` | +| enableRobotsTXT | string | No | enable robots.txt | `true` | `true` | +| paginate | number | Yes | Default paginate | 10 | 10 | +| params.brand | string | Yes | brand | `"HOME"` | `"LADDER"` | +| params.avatarURL | string | No | Gravatar photo of the author | `"/images/avatar.png"` `replace the photo or change the path` | `"/images/avatar.png"` | +| params.author | string | No | Home page author name | `"Hugo Ladder"` | `"Hugo Ladder"` | +| params.authorDescription | string | No | Home page author description | `"A clean, fast hugo theme focused on Reading"` | `"A clean, fast hugo theme focused on Reading"` | +| params.info | string | No | Home page website info | `"Ladder is a clean, simple but beautiful theme with awesome features"` | `"Ladder is a clean, simple but beautiful theme with awesome features"` | +| params.favicon | string | No | icon photo of the website | `"/images/avatar.png"` | `"/images/avatar.png"` | +| params.options.showDarkMode | bool | No | enable dark mode button in nav | `true` | `true` | +| params.options.enableImgZooming | bool | No | enable zooming when click img within post | `true` | `true` | +| params.options.enableMultiLang | bool | No | enable multi-language support | `true` | `false` | +| params.darkModeTheme | string | yes | Adds theme for dark mode | `data-dark-mode` | `data-dark-mode` or `icy-dark-mode` | +| params.guestbook.title | string | No | guestbooke title | `"Guestbook"` | `"Guestbook"` | +| params.guestbook.description | string | No | guestbooke description | `"Leave a comment below. It could be anything –- question, appreciation, information, or even humor."` | `"Leave a comment below. It could be anything –- question, appreciation, information, or even humor."` | +| taxonomies.series | string | Yes | enable series | `"series"` | `"series"` | +| ptaxonomies.tags | string | Yes | enable tags | `"tags"` | `"tags"` | + +### Social Icons Configuration + +Social Icons are optional. To use them you will need to set at least all the following required parameters for each icon. + +| Configuration | Type | Required | Description | Example | +| ------------- | ------ | -------- | ---------------- | ------------------------------------- | +| name | string | Yes | Icon name. | `"Github"` | +| pre | string | Yes | icon svg. | `"find in https://feathericons.com/"` | +| url | string | Yes | URL to redirect. | `"https://github.com/guangzhengli/"` | + +An example: + +```yml + social: + - name: GitHub + pre: >- + + url: 'https://github.com/guangzhengli/hugo-theme-ladder' + - name: Dashboard + pre: >- + + url: 'https://umami-ochre-nu.vercel.app/share/R1lHz7QY/hugo-ladder-exampleSite' +``` + +### Menu Items Configurations + +Menu Items are optional. To use them you will need to set all the following required parameters for each icon. + +| Configuration | Type | Required | Description | Example | +| ------------- | ------ | -------- | ---------------- | --------- | +| name | string | Yes | Menu Item name. | `"Blog"` | +| weight | int | Yes | Menu Item order. | `1` | +| url | string | Yes | URL to redirect. | `"/blog"` | + +An example: + +```yml +menu: + main: + - name: Blog + url: /blog + weight: 1 + - name: Tags + url: /tags + weight: 2 + - name: Archive + url: /archives + weight: 3 + - name: Guestbook + url: /guestbook + weight: 4 + - name: Dashboard + url: https://umami-ochre-nu.vercel.app/share/R1lHz7QY/hugo-ladder-exampleSite + weight: 5 +``` + +## Complete Example + +This is a complete configuration example with some recommended values. + +```yml +baseURL: 'https://hugo-ladder.pages.dev' +title: LADDER +theme: hugo-theme-ladder +license: MIT +licenselink: 'https://github.com/guangzhengli/hugo-theme-ladder/blob/master/LICENSE' +description: 'A fast, clean Hugo theme' +homepage: 'https://hugo-ladder.pages.dev' +defaultContentLanguage: 'en' +googleAnalytics: G-4WXJ5TEK2S +paginate: 10 +menu: + main: + - name: Blog + url: /blog + weight: 1 + - name: Tags + url: /tags + weight: 2 + - name: Archive + url: /archives + weight: 3 + - name: Guestbook + url: /guestbook + weight: 4 + - name: Dashboard + url: https://umami-ochre-nu.vercel.app/share/R1lHz7QY/hugo-ladder-exampleSite + weight: 5 +params: + brand: HOME + avatarURL: /images/avatar.png + author: Hugo Ladder + authorDescription: A clean, fast hugo theme focused on Reading + info: Ladder is a clean, simple but beautiful theme with awesome features + favicon: /images/avatar.png + options: + showDarkMode: true + enableImgZooming: true + enableMultiLang: true + darkModeTheme: data-dark-mode + #darkModeTheme: icy-dark-mode + comments: + giscus: + enable: true + repo: guangzhengli/hugo-ladder-exampleSite + repo_id: R_kgDOHyVOjg + category: Announcements + category_id: DIC_kwDOHyVOjs4CQsH7 + mapping: pathname + position: top + lang: en # pick a language from https://github.com/giscus/giscus/tree/main/locales + utteranc: + enable: false + repo: guangzhengli/blog-comments + issueTerm: pathname + analytics: + google: + SiteVerificationTag: xxx + umami: + enable: true + website_id: 2320eaa6-a90b-471c-b6ca-e79dadde8c4c + url: https://umami-ochre-nu.vercel.app/hugo-ladder.js + guestbook: + title: Guestbook + description: Leave a comment below. It could be anything –- question, appreciation, information, or even humor. + social: + - name: GitHub + pre: >- + + url: 'https://github.com/guangzhengli/hugo-theme-ladder' + - name: Dashboard + pre: >- + + url: 'https://umami-ochre-nu.vercel.app/share/R1lHz7QY/hugo-ladder-exampleSite' +languages: + en: + languageName: EN + zh: + languageName: 中 + author: Ladder 主题 + authorDescription: 一个美观，快速并且专注于阅读的主题 + info: 帮助开发者构建一个免费并且漂亮的博客网站，记录自己的思考并且提高自己的影响力 + guestbook: + title: 留言板 + description: 您的评论，会让该网站更精彩！ + menu: + main: + - name: 文章 + url: /blog + weight: 1 + - name: 分类 + url: /tags + weight: 2 + - name: 历史文章 + url: /archives + weight: 3 + - name: 留言板 + url: /guestbook + weight: 4 + - name: 网站统计 + url: https://umami-ochre-nu.vercel.app/share/R1lHz7QY/hugo-ladder-exampleSite + weight: 5 +taxonomies: + series: series + tag: tags + +``` + +## Content Management + +If you create a new posts, it is recommended to fill the configuration which means: + +```markdown +title: +date: {{ .Date }} +tags: [] +series: [] +featured: true +``` + +* `title` post title +* `date` published date +* `tags` tags +* `series` series, it will be show related post below the content. +* `featured` it will be show in home page featured post, `true` or `false` diff --git a/docs/home.md b/docs/home.md new file mode 100644 index 0000000..a450d15 --- /dev/null +++ b/docs/home.md @@ -0,0 +1,14 @@ +# Welcome to the hugo-ladder docs! + +## Basic Usage + +* [Quick Start](quick-start.md) +* [Configurations](configurations.md) + +## Extra Guides + +* [Multi Language](multi-language.md) +* [Comment System](comment-system.md) +* [Analytics](analytics.md) +* [Analytics Umami](umami.md) + diff --git a/docs/multi-language.md b/docs/multi-language.md new file mode 100644 index 0000000..7540ef2 --- /dev/null +++ b/docs/multi-language.md @@ -0,0 +1,88 @@ +# Multilingual-Mode + +* [Available Languages](#available-languages) +* [Configure Languages](#configure-languages) +* [Translation File Example](#translation-file-example) + +## Available Languages + +This theme supports the following languages: + +- English +- Simplified Chinese + +## Configure languages + +Go to [this Hugo documentation page](https://gohugo.io/content-management/multilingual/#configure-languages) to configure one or multiple languages for your website. + +## Translation File Example + +```toml +[blog] +one = "blog" +other = "blog" + +[tags] +one = "tag" +other = "tags" + +[archive] +one = "archive" +other = "archive" + +[series] +one = "series" +other = "series" + +[reading_time] +one = "One minute" +other = "{{ .Count }} min" + +[word_count] +one = "one word" +other = "{{ .Count }} words" + +[related_resources] +other = "Related Resources" + +[featured_posts] +one = "Featured Posts" +other = "Featured Posts" +``` + + + +```toml +[blog] +one = "文章" +other = "文章" + +[tags] +one = "分类" +other = "分类" + +[archive] +one = "历史文章" +other = "历史文章" + +[series] +one = "系列文章" +other = "系列文章" + +[reading_time] +one = "1 分钟" +other = "{{ .Count }} 分钟" + +[word_count] +one = "字" +other = "{{ .Count }} 字" + +[related_resources] +one = "相关系列文章推荐" +other = "相关系列文章推荐" + +[featured_posts] +one = "推荐阅读" +other = "推荐阅读" +``` + diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..5bcfca8 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,15 @@ +## how to install + +Just click `Use this template` to create your blog site by + +![4dmtph](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/4dmtph.png) + +Create a new repository(GitHub Pages) from hugo-ladder-exampleSite to enter : `username.github.io`. + +> **replace the username by your GitHub account** + +Then configure the GitHub page setting following: + +![nsrExo](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/nsrExo.png) + +🎉🎉🎉 Open the browser and enter: https://username.github.io 🎉🎉🎉 \ No newline at end of file diff --git a/docs/umami.md b/docs/umami.md new file mode 100644 index 0000000..59aa9f8 --- /dev/null +++ b/docs/umami.md @@ -0,0 +1,46 @@ +This article is about how to integrate [umami](https://umami.is/) website analytics to your website for free. The database use [postgres](https://supabase.com/docs/guides/database) with 500M storage limit provided by [supabase](https://app.supabase.com/). + +The [umami](https://umami.is/) service is hosted with [vercel](https://vercel.com/). Thanks to the excellent service capabilities of cloud vendors, you can integrate *umami* in less than 10 minutes. You can see the umami dashboard by clicking the [Dashboard](https://umami-ochre-nu.vercel.app/share/o3zAba1V/guangzhengli). + +## Create a database + +The database use [postgres](https://supabase.com/docs/guides/database) with 500M storage limit provided by [supabase](https://app.supabase.com/). You can create a supabase account, click `new project`, and enter the database passowrd to create an ProgresSQL database service. + +![cN3Zg4](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/cN3Zg4.png) + +It will take a few minutes to create the database service, and you can get the `DATABASE_URL` after it's done. + +![image-20220815182141638](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/image-20220815182141638.png) + +## Hosting umami + +The [umami](https://umami.is/) service is hosted with [vercel](https://vercel.com/), Once you have created the database instance, you can deploy the umami service with click deploy button in the [Running on Vercel](https://umami.is/docs/running-on-vercel) document. + +1. Fork the https://github.com/mikecao/umami project to your GitHub account. +2. Create an account on Vercel. +3. From the dashboard page click Import Project then specify the URL to your fork of the project on GitHub. +4. Add the required environment variables to your Vercel project. These values are defined in the Configure umami step from Install. + 1. DATABASE_URL: Connection string for your database. This is the only required variable. + 2. TRACKER_SCRIPT_NAME: Allows you to assign a custom name to the tracker script different from the default `umami`. This is to help you avoid some ad-blockers. I used `hugo-ladder` on this project. + +5. Enter `yarn build && yarn update-db` to the `BUILD COMMAND`, which will migrate the tables of umami to database automatically. +6. Deploy and visit your application at .vercel.app. +7. Follow the Getting started guide starting from the Login step and be sure to change the default password. + +![gePzXI](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/gePzXI.png) + +Of course, if you want to import tables yourself, you can also get the tables from here https://github.com/umami-software/umami/blob/master/sql/schema.postgresql.sql. + +## umami configuration + +After deploying umami in vercel you will get a `.vercel.app` address which login with the default account: *admin* and password: *umami*. + +You can change the default password and `Add webiste`, enter the `Name` and `Domain`, and click `enable share URL` so that anyone can access the dashboard. + +Then you can get `data-website-id` and `src` values by click `Get tracking code`，enter the value to the `hugo-ladder` configuration `params.analytics.umami.website_id` , `params.analytics.umami.url`. + +![OZcU7U](https://cdn.jsdelivr.net/gh/guangzhengli/PicURL@master/uPic/OZcU7U.png) + + + +Link to original article: https://guangzhengli.com/en/blog/en/how-to-integrate-umami-for-free-to-blog-site/ \ No newline at end of file