diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 4845f600..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,30 +0,0 @@ -# CONTRIBUTING - -## How to contribute to this project - -First, fork this repository by clicking the fork button. - -Next, clone your forked repo. - -```bash -git clone --recursive https://github.com/hugo-fixit/docs.git fixit-docs && cd fixit-docs -``` - -Then, install the dev dependencies. - -```bash -npm install -``` - -And now you are ready to go! - -Here are some useful commands. - -```bash -# run a local debugging server with watch -npm run server -# run a local debugging server with watch in production environment -npm run server:production -``` - -Finally, create a new pull request at to submit your contribution 🎉 diff --git a/README.en.md b/README.en.md index 2b16c472..04e09342 100644 --- a/README.en.md +++ b/README.en.md @@ -4,12 +4,51 @@ [![Preview environment](https://img.shields.io/github/deployments/hugo-fixit/docs/Preview?style=flat&label=Preview&logo=vercel)](https://pre.fixit.lruihao.cn/) [![Hugo](https://img.shields.io/badge/Hugo-%5E0.112.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/) -[FixIt](https://github.com/hugo-fixit/FixIt) is a **clean**, **elegant** but **advanced** blog theme for [Hugo](https://gohugo.io/) developed by [Lruihao](https://github.com/Lruihao "Follow me on GitHub"). - 👉 [中文](README.md) | English -## Contributing Documentation +[FixIt](https://github.com/hugo-fixit/FixIt) theme documentation is mainly divided into: [Documentation](https://fixit.lruihao.cn/documentation/), [Guides](https://fixit.lruihao.cn/guides/) two major sections, welcome everyone to initiate a PR to improve the theme documentation. + +## System requirements + +- [Node.js](https://nodejs.org/): >= 18.0.0 +- [Go](https://go.dev/dl/) +- [Hugo](https://gohugo.io/installation/): >= 0.112.0 (extended version) + +## Contributing + +First, fork this repository by clicking the fork button. + +Next, clone your forked repo. + +```bash +git clone https://github.com/hugo-fixit/docs.git fixit-docs && cd fixit-docs +``` + +Then, install the dev dependencies. + +```bash +npm install +``` + +And now you are ready to go! + +Here are some useful commands. + +```bash +# run a local debugging server with watch +npm run server +# run a local debugging server with watch in production environment +npm run server:production +# see Edit the theme section +npm run server:development +``` + +## Edit the theme + +If you want to do docs-related theme changes, the simplest way is to have both `fixit-docs` and `FixIt` cloned as sibling directories, and then run: -FixIt theme documentation is mainly divided into: [Documentation](https://fixit.lruihao.cn/documentation/), [Guides](https://fixit.lruihao.cn/guides/) two major sections, welcome everyone to initiate a PR to improve the theme documentation. +```bash +HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" +``` -If you want to make theme-related changes, please head to the [hugo-fixit/FixIt](https://github.com/hugo-fixit/FixIt) repository. +Finally, create a new pull request at to submit your contribution 🎉 diff --git a/README.md b/README.md index aaf2068e..853bf822 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,49 @@ 👉 中文 | [English](README.en.md) -[FixIt](https://github.com/hugo-fixit/FixIt) 是一个由 [Lruihao](https://github.com/Lruihao "在 GitHub 上关注我") 开发的**简洁**、**优雅**且**高效**的 [Hugo](https://gohugo.io/) 博客主题。 +[FixIt](https://github.com/hugo-fixit/FixIt) 主题文档主要分为：[文档](https://fixit.lruihao.cn/zh-cn/documentation/)、[教程](https://fixit.lruihao.cn/zh-cn/guides/) 两大板块，欢迎大家发起 PR 完善主题文档。 + +## 系统依赖 + +- [Node.js](https://nodejs.org/): >= 18.0.0 +- [Go](https://go.dev/dl/) +- [Hugo](https://gohugo.io/installation/): >= 0.112.0 (extended version) ## 贡献文档 -FixIt 主题文档主要分为：[文档](https://fixit.lruihao.cn/zh-cn/documentation/)、[教程](https://fixit.lruihao.cn/zh-cn/guides/)三个大的板块，欢迎大家发起 PR 完善主题文档。 +首先，点击 fork 按钮 fork 本仓库。 + +然后，克隆你 fork 的仓库。 + +```bash +git clone https://github.com/hugo-fixit/docs.git fixit-docs && cd fixit-docs +``` + +接着，安装开发依赖。 + +```bash +npm install +``` + +最后，你就可以开始了！ + +这里有一些有用的命令。 + +```bash +# 运行带有监听文件变化的本地调试服务器 +npm run server +# 运行带有监听文件变化的本地调试服务器（生产环境） +npm run server:production +# 查看编辑主题部分 +npm run server:development +``` + +## 编辑主题 + +如果你想做与文档相关的主题更改，最简单的方法是将 `fixit-docs` 和 `FixIt` 克隆为兄弟目录，然后运行： -请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解贡献该项目的基本信息。 +```bash +HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" +``` -如果你想进行与主题相关的更改，请前往 [hugo-fixit/FixIt](https://github.com/hugo-fixit/FixIt) 仓库。 +最后，在 创建一个新的 pull request 来提交你的贡献 🎉 diff --git a/config/_default/module.toml b/config/_default/module.toml index a70d90e2..9d020684 100644 --- a/config/_default/module.toml +++ b/config/_default/module.toml @@ -3,9 +3,6 @@ # See: https://gohugo.io/hugo-modules/configuration/#module-config-imports # ------------------------------------------------------------------------------------- -# equivalent to `env HUGO_MODULE_REPLACEMENTS="github.com/hugo-fixit/FixIt -> FixIt"` -# replacements = "github.com/hugo-fixit/FixIt -> FixIt" - [[imports]] path = "github.com/hugo-fixit/FixIt" diff --git a/content/en/documentation/getting-started/index.md b/content/en/documentation/getting-started/index.md index b61a8d1b..fb7bf0fc 100644 --- a/content/en/documentation/getting-started/index.md +++ b/content/en/documentation/getting-started/index.md @@ -6,6 +6,7 @@ type: posts author: name: Lruihao link: https://lruihao.cn + description: Learn to create a Hugo FixIt site in minutes. resources: - name: featured-image @@ -24,7 +25,7 @@ menu: name: Getting Started title: Learn to create a Hugo FixIt site in minutes. parent: documentation - weight: 1 + weight: 2 params: icon: fa-brands fa-readme --- diff --git a/content/en/documentation/installation.md b/content/en/documentation/installation.md new file mode 100644 index 00000000..fcb9ec48 --- /dev/null +++ b/content/en/documentation/installation.md @@ -0,0 +1,194 @@ +--- +title: Installation Theme +linkTitle: Installation +date: 2024-01-18T10:29:25+08:00 +type: posts +categories: + - Documentation +tags: + - Installation +menu: + main: + title: Install FixIt Theme for your Hugo site in a few steps. + parent: documentation + weight: 1 + params: + icon: fa-brands fa-readme +--- + +Install **FixIt** theme for your Hugo site in a few steps. + + + +1. Configure the default theme to FixIt in `hugo.toml`, e.g. `theme = "FixIt"` +2. Install the theme by one of the following ways. + +## Prerequisites + +Thanks to the simplicity of Hugo, [Hugo][hugo] may be the only dependency of this theme. + +Although not required in all cases, [Git][git], [Go][go], [Dart Sass][dart-sass] and [Node.js][node.js] are commonly used when working with Hugo. + +Git is required to: + +- Build Hugo from source +- Use the [Hugo Modules][hugo-modules] feature +- Install a theme as a Git submodule +- Access [commit information][commit-info] from a local Git repository +- Host your site with services such as [CloudCannon][cloudcannon], [Cloudflare Pages][cloudflare-pages], [GitHub Pages][github-pages], [GitLab Pages][gitlab-pages], and [Netlify][netlify] + +Go is required to: + +- Build Hugo from source +- Use the Hugo Modules feature + +Dart Sass is required to transpile Sass to CSS when using the latest features of the Sass language. + +Node.js is required to: + +- Use the FixIt CLI +- Some Automation Tools, e.g. [atomic-algolia]({{< relref path="/guides/algolia-atomic" >}}) + +Please refer to the relevant documentation for installation instructions: + +- [Hugo][hugo-install] (extended edition, v0.112.0 or later) +- [Git][git-install] +- [Go][go-install] +- _[Dart Sass][dart-sass-install] (not used yet)_ +- [Node.js][node-install] (v16.0.0 or later) + +## Manual + +You can download the [latest release :(fa-regular fa-file-archive fa-fw): .zip file][releases] of the theme and extract it in the `themes` directory. + +To upgrade the theme by replacing the old theme with the new one. + +## Git Clone + +In this way, just clone the [FixIt][fixit] theme into the `themes` directory. + +```bash +git clone https://github.com/hugo-fixit/FixIt.git themes/FixIt +``` + +To upgrade the theme by pulling the latest commits from the repository. + +```bash +cd themes/FixIt +git pull +``` + +## Git Submodule {#git-submodule} + + +{{< link "https://github.com/hugo-fixit/hugo-fixit-starter1" "A Template base on Git Submodule" "" true >}} + +Initialize an empty Git repository in the current directory. + +```bash +git init +``` + +Add [FixIt][fixit] to your project as a [Git submodule][git-submodule] stored in the `themes` directory. + +```bash +git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt +``` + +To use the version on the `dev` branch, you can use the following command: + +```bash +git submodule add -b dev https://github.com/hugo-fixit/FixIt.git themes/FixIt + +# Alternatively, switch the submodule branch from `master` to `dev`: +git submodule set-branch -b dev themes/FixIt +``` + +To upgrade the theme by using the following command: + +```bash +git submodule update --remote --merge themes/FixIt +``` + +## Hugo Module {#hugo-module} + + +{{< link "https://github.com/hugo-fixit/hugo-fixit-starter" "A Template base on Hugo Module" "" true >}} + +{{< admonition tip >}} +In this way, you don't need to configure `theme = "FixIt"` in `hugo.toml`. +{{< /admonition >}} + +The easiest way to use a [Module][hugo-modules] for a theme is to import it in the config. See [Use Hugo Modules][use-hugo-modules]. + +1. Initialize the hugo module system: `hugo mod init github.com//` +2. Import the theme: + + ```toml + [module] + [[module.imports]] + path = "github.com/hugo-fixit/FixIt" + ``` + +To update or manage versions, you can use `hugo mod get`. + +```bash +# Update all modules +hugo mod get -u +# Update all modules recursively +hugo mod get -u ./... +# Update one module +hugo mod get -u github.com/hugo-fixit/FixIt +# Get a specific version (e.g. v0.3.2, @latest, @master, @dev) +hugo mod get github.com/hugo-fixit/FixIt@v0.3.2 +``` + +## CLI + +FixIt provides an [official CLI][fixit-cli] for quickly scaffolding ambitious Hugo FixIt site. It provides two ways to quickly scaffold Hugo FixIt site based on Git Submodule or Hugo Module, and provides the ability to check the latest version of the FixIt theme. See the [FixIt CLI docs][fixit-cli] for more details. + +```bash +npm install -g fixit-cli +fixit create my-blog +``` + + + +{{< admonition danger "Tip" >}} +The CLI assumes prior knowledge of Hugo and FixIt. If you are new to Hugo or FixIt, we strongly suggest going through [the theme documentation](../) without any scaffold tools before using the CLI. +{{< /admonition >}} + +## Comparison + +| | Manual | Git Clone | Git Submodule | Hugo Module | +| ----------------------------- | :----------------: | :----------------: | :----------------: | :----------------: | +| Prerequisites | Hugo | Hugo, Git | Hugo, Git | Hugo, Git, Go | +| Easy to install? | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| Easy to upgrade or downgrade? | :heavy_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | +| Download speed? | :x: | :x: | :heavy_check_mark: | :white_check_mark: | +| Automatic updates? | :x: | :x: | :white_check_mark: | :white_check_mark: | +| Latest version available? | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | + + +[hugo]: https://gohugo.io/ +[hugo-install]: https://gohugo.io/installation/ +[git]: https://git-scm.com/ +[git-install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[go]: https://go.dev/ +[go-install]: https://go.dev/doc/install +[dart-sass]: https://gohugo.io/hugo-pipes/transpile-sass-to-css/#dart-sass +[dart-sass-install]: https://gohugo.io/hugo-pipes/transpile-sass-to-css/#dart-sass +[node.js]: https://nodejs.org/ +[node-install]: https://nodejs.org/en/download/ +[commit-info]: https://gohugo.io/variables/git/ +[cloudcannon]: https://cloudcannon.com/ +[cloudflare-pages]: https://pages.cloudflare.com/ +[github-pages]: https://pages.github.com/ +[gitlab-pages]: https://docs.gitlab.com/ee/user/project/pages/ +[netlify]: https://www.netlify.com/ +[fixit]: https://github.com/hugo-fixit/FixIt +[fixit-cli]: https://github.com/hugo-fixit/fixit-cli +[releases]: https://github.com/hugo-fixit/FixIt/releases +[git-submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[hugo-modules]: https://gohugo.io/hugo-modules/ +[use-hugo-modules]: https://gohugo.io/hugo-modules/use-modules/ diff --git a/content/zh-cn/documentation/installation.md b/content/zh-cn/documentation/installation.md new file mode 100644 index 00000000..f613e05b --- /dev/null +++ b/content/zh-cn/documentation/installation.md @@ -0,0 +1,12 @@ +--- +title: 安装主题 +linkTitle: 安装 +date: 2024-01-18T10:29:25+08:00 +type: posts +categories: + - Documentation +tags: + - Installation +--- + + \ No newline at end of file diff --git a/hugo.work b/hugo.work new file mode 100644 index 00000000..f1ff32be --- /dev/null +++ b/hugo.work @@ -0,0 +1,4 @@ +go 1.19 + +use . +use ../FixIt diff --git a/package.json b/package.json index f19d67e1..b3d49ad1 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "build": "hugo -v --gc --minify", "server": "hugo server -D --disableFastRender --navigateToChanged --ignoreCache --bind 0.0.0.0", "server:production": "npm run server -- -e production", + "server:development": "cross-env HUGO_MODULE_WORKSPACE=hugo.work npm run server -- --ignoreVendorPaths \"**\"", "update:theme": "hugo mod get -u github.com/hugo-fixit/FixIt@latest && hugo mod tidy" }, "devDependencies": {