From f613f31ef0a75a96aef5ff04143f22600e0a14f4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 5 Aug 2024 12:37:33 -0400 Subject: [PATCH 1/5] [CI] Prettier: run over all content --- .cspell.yml | 1 - .prettierignore | 17 ++------- README.md | 2 +- content/en/_index.md | 18 ++++++---- content/en/blog/2024/hello.md | 2 +- content/en/blog/_index.md | 2 +- content/en/community/_index.md | 2 +- content/en/docs/examples.md | 7 ++-- content/en/docs/get-started/_index.md | 51 ++++++++++++++++++++------- content/en/search.md | 1 - hugo.yaml | 4 +-- package.json | 2 +- 12 files changed, 64 insertions(+), 45 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 8c577c5..0fa9991 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -25,4 +25,3 @@ languageSettings: words: - CNCF - Docsy - diff --git a/.prettierignore b/.prettierignore index 68d87df..427ad12 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,15 +1,2 @@ -.* -/* -!/content -/content/* -!/content/en -/content/en/* - -!/content/en/docs -/content/en/docs/* -!/content/en/docs/_index.md - -!/content/en/docs/adding-content -/content/en/docs/adding-content/* - -!/content/en/docs/adding-content/lookandfeel.md +/themes +/layouts diff --git a/README.md b/README.md index 12391b8..51c8283 100644 --- a/README.md +++ b/README.md @@ -11,5 +11,5 @@ For a preview, see [cncf-docsy-starter.netlify.app]. [cncf-docsy-starter.netlify.app]: https://cncf-docsy-starter.netlify.app/ [Docsy]: https://github.com/google/docsy -[Hugo]:https://gohugo.io +[Hugo]: https://gohugo.io [Netlify]: https://netlify.com diff --git a/content/en/_index.md b/content/en/_index.md index a16c069..ea399d2 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -11,6 +11,8 @@ show_banner: true --- {{% blocks/cover title="Docsy Starter" image_anchor="top" height="full" %}} + + {{% param description %}} {.display-6} @@ -18,10 +20,10 @@ show_banner: true Get started {.p-initial .my-5} -{{% blocks/link-down color="info" %}} -{{% /blocks/cover %}} +{{% blocks/link-down color="info" %}} {{% /blocks/cover %}} {{% blocks/lead color="primary" %}} + Docsy is a theme for the Hugo static site generator that's specifically designed for technical documentation sets. Our aim is to help you get a working documentation site up and running as easily as possible, so you can concentrate @@ -35,14 +37,18 @@ on creating great content for your users. {{% blocks/section color="dark" type="row" %}} {{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}} -As well as our example site, there's a growing number of projects using Docsy for their doc sites. -{{% /blocks/feature %}} +As well as our example site, there's a growing number of projects using Docsy +for their doc sites. -{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/google/docsy" %}} -We do a [Pull Request](https://github.com/google/docsy/pulls) contributions workflow on **GitHub**. New users are always welcome! {{% /blocks/feature %}} +{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/google/docsy" %}} + +We do a [Pull Request](https://github.com/google/docsy/pulls) contributions +workflow on **GitHub**. New users are always welcome! + +{{% /blocks/feature %}} {{% blocks/feature icon="fa-brands fa-x-twitter" title="Follow us on Twitter!" url="https://twitter.com/docsydocs" %}} Find out about new features and how our users are using Docsy. diff --git a/content/en/blog/2024/hello.md b/content/en/blog/2024/hello.md index 0f8063a..3e64bdf 100644 --- a/content/en/blog/2024/hello.md +++ b/content/en/blog/2024/hello.md @@ -10,5 +10,5 @@ including Continuous Integration (CI) tooling, of existing CNCF websites built using [Hugo], [Docsy], and deployed on [Netlify]. [Docsy]: https://github.com/google/docsy -[Hugo]:https://gohugo.io +[Hugo]: https://gohugo.io [Netlify]: https://netlify.com diff --git a/content/en/blog/_index.md b/content/en/blog/_index.md index 9ad71a4..c63b89f 100644 --- a/content/en/blog/_index.md +++ b/content/en/blog/_index.md @@ -1,4 +1,4 @@ --- title: Blog -menu: {main: {weight: 50}} +menu: { main: { weight: 50 } } --- diff --git a/content/en/community/_index.md b/content/en/community/_index.md index c2562d6..9ab8481 100644 --- a/content/en/community/_index.md +++ b/content/en/community/_index.md @@ -1,5 +1,5 @@ --- title: Community -menu: {main: {weight: 40}} +menu: { main: { weight: 40 } } # Content below, if any, will be added to the community page. --- diff --git a/content/en/docs/examples.md b/content/en/docs/examples.md index 0874d9e..1bbeb8d 100644 --- a/content/en/docs/examples.md +++ b/content/en/docs/examples.md @@ -4,8 +4,11 @@ weight: 500 description: THIS IS SAMPLE CONTENT --- -One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you've got a production site up and running with Docsy! +One of the best ways to see what Docsy can do, and learn how to configure a site +with it, is to see some real projects. In addition to our provided Docsy Example +Project, there are several live sites already using the theme. Please add your +own examples once you've got a production site up and running with Docsy! ## Docsy theme examples -Example sites that have low to no customization: ... \ No newline at end of file +Example sites that have low to no customization: ... diff --git a/content/en/docs/get-started/_index.md b/content/en/docs/get-started/_index.md index c0ac5c4..c353274 100644 --- a/content/en/docs/get-started/_index.md +++ b/content/en/docs/get-started/_index.md @@ -1,4 +1,3 @@ - --- title: Get started weight: 100 @@ -6,27 +5,53 @@ weight: 100 description: THIS IS SAMPLE CONTENT --- -As you saw in our introduction, Docsy is a [Hugo](https://gohugo.io) theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites. +As you saw in our introduction, Docsy is a [Hugo](https://gohugo.io) theme, +which means that if you want to use Docsy, you need to set up your website +source so that the Hugo static site generator can find and use the Docsy theme +files when building your site. The simplest way to do this is to copy and edit +our example site, though we also provide instructions for adding the Docsy theme +manually to new or existing sites. -If you want to build and test your site locally you also need to be able to run Hugo itself, either by installing it and any other required dependencies, or by using our provided Docker container. +If you want to build and test your site locally you also need to be able to run +Hugo itself, either by installing it and any other required dependencies, or by +using our provided Docker container. -This page describes Docsy's installation options and helps you choose the appropriate setup guide to get started. +This page describes Docsy's installation options and helps you choose the +appropriate setup guide to get started. ## Installation options -Hugo offers multiple options for using themes, all of which are supported by Docsy. - -* **Adding the theme as a Hugo Module**: [Hugo Modules](https://gohugo.io/hugo-modules/) are the simplest and latest way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it's easy to keep the theme up to date in your site. Our [example site](https://github.com/google/docsy-example) uses Docsy as a Hugo Module. -* **Adding the theme as a Git submodule**: Adding the theme as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) also lets Hugo use the theme files from their own repo, though is more complicated to maintain than the Hugo modules approach. This is the approach used in older versions of the Docsy example site and is still supported. -* **Cloning the theme files**: If you don't want Hugo to have to get the theme files from an external repo (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the files directly into your site source. +Hugo offers multiple options for using themes, all of which are supported by +Docsy. + +- **Adding the theme as a Hugo Module**: + [Hugo Modules](https://gohugo.io/hugo-modules/) are the simplest and latest + way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme + files from the main Docsy repo at your chosen revision, and it's easy to keep + the theme up to date in your site. Our + [example site](https://github.com/google/docsy-example) uses Docsy as a Hugo + Module. +- **Adding the theme as a Git submodule**: Adding the theme as a + [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) also lets + Hugo use the theme files from their own repo, though is more complicated to + maintain than the Hugo modules approach. This is the approach used in older + versions of the Docsy example site and is still supported. +- **Cloning the theme files**: If you don't want Hugo to have to get the theme + files from an external repo (for example, if you want to customize and + maintain your own copy of the theme directly, or your deployment choice + requires you to include a copy of the theme in your repository), you can clone + the files directly into your site source. ## Migration and backward compatibility If you have an existing site that uses Docsy as a Git submodule, and you would -like to update it to use Hugo Modules, follow our [migration -guide](https://www.docsy.dev//docs/updating/convert-site-to-module/). If you're -not ready to migrate yet, don't worry! Your site will continue to work as usual. +like to update it to use Hugo Modules, follow our +[migration guide](https://www.docsy.dev//docs/updating/convert-site-to-module/). +If you're not ready to migrate yet, don't worry! Your site will continue to work +as usual. ## Setup guides -Follow the setup guide for your chosen approach. If you're new to Docsy and not sure which guide to follow, we recommend following the Use Docsy as a Hugo Module guide as a simple and easily maintained option. +Follow the setup guide for your chosen approach. If you're new to Docsy and not +sure which guide to follow, we recommend following the Use Docsy as a Hugo +Module guide as a simple and easily maintained option. diff --git a/content/en/search.md b/content/en/search.md index 4cde3a9..394feea 100644 --- a/content/en/search.md +++ b/content/en/search.md @@ -2,4 +2,3 @@ title: Search Results layout: search --- - diff --git a/hugo.yaml b/hugo.yaml index 61fae72..a8472d8 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -65,8 +65,8 @@ imaging: params: copyright: authors: >- - Project Authors | - [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | + Project Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) + | # from_year: 2024 github_repo: https://github.com/chalin/docsy-starter gcs_engine_id: 011217106833237091527:la2vtv2emlw # CUSTOMIZE # FIXME get an ID for the starter? diff --git a/package.json b/package.json index 882955b..249c31e 100644 --- a/package.json +++ b/package.json @@ -56,4 +56,4 @@ "singleQuote": true }, "spelling": "cSpell:ignore docsy hugo HTMLTEST pkgs netlify precheck postbuild -" -} \ No newline at end of file +} From 878d6b630e2d0dff8037b1bc87b36b08ca278d5d Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 5 Aug 2024 19:55:28 -0400 Subject: [PATCH 2/5] [CI] Add check-format workflow --- .github/workflows/check-format.yml | 32 ++++++++++++++++++++++++++++++ package.json | 15 +++++++++----- 2 files changed, 42 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/check-format.yml diff --git a/.github/workflows/check-format.yml b/.github/workflows/check-format.yml new file mode 100644 index 0000000..6f91f5b --- /dev/null +++ b/.github/workflows/check-format.yml @@ -0,0 +1,32 @@ +name: Files + +on: + pull_request: + +jobs: + check-filenames: + name: FILENAME check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: npm run check:filenames + + check-formatting: + name: FILE FORMAT + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Create NPM cache-hash input file + run: | + mkdir -p tmp + jq '{devDependencies, engines, gitHubActionCacheKey}' package.json > tmp/package-ci.json + + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + cache: npm + cache-dependency-path: tmp/package-ci.json + + - name: Check file format + run: npm run check:format --ignore-scripts diff --git a/package.json b/package.json index 249c31e..e0e20c2 100644 --- a/package.json +++ b/package.json @@ -4,29 +4,34 @@ "__check:links": "make --keep-going check-links", "_build": "npm run _hugo-dev --", "_check:format": "npx prettier --check .", - "_check:links": "HTMLTEST_ARGS='--log-level 1 --skip-external' npm run __check:links", "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)", + "_check:links": "HTMLTEST_ARGS='--log-level 1 --skip-external' npm run __check:links", "_diff:check": "git diff --name-only --exit-code", + "_filename-error": "echo 'ERROR: the following files violate naming conventions; fix using: `npm run fix:filenames`'; echo; npm run -s _ls-bad-filenames; exit 1", + "_filenames-to-kebab-case": "find assets content -name '*_*' ! -name '[_.]*' -exec sh -c 'mv \"$1\" \"${1//_/-}\"' _ {} \\;", "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}", - "_hugo": "hugo --cleanDestinationDir", "_hugo-dev": "npm run _hugo -- -e dev -DFE", + "_hugo": "hugo --cleanDestinationDir", + "_ls-bad-filenames": "find assets content -name '*_*' ! -name '[_.]*'", "_prepare:docsy": "cd themes/docsy && npm install", - "_serve": "npm run _hugo-dev -- --minify serve", + "_serve": "npm run _hugo-dev -- serve --minify --disableFastRender --renderToMemory", "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"", "build:production": "npm run _hugo -- --minify", "build": "npm run _build --", + "check:filenames": "test -z \"$(npm run -s _ls-bad-filenames)\" || npm run -s _filename-error", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", "check:links:all": "HTMLTEST_ARGS= npm run _check:links", "check:links": "npm run _check:links", "clean": "rm -Rf public", "diff:check": "npm run _diff:check || (echo; echo 'WARNING: the files above have not been committed'; echo)", + "fix:filenames": "npm run _filenames-to-kebab-case", "fix:format": "npm run _check:format -- --write", "get:submodule": "npm run _get:${GET:-submodule}", "make:public": "git init -b main public", - "precheck:links:all": "npm run build", - "precheck:links": "npm run build", "postbuild:preview": "npm run _check:links--warn", "postbuild:production": "npm run _check:links--warn", + "precheck:links:all": "npm run build", + "precheck:links": "npm run build", "prepare": "npm run seq -- get:submodule _prepare:docsy", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", "serve": "npm run _serve", From 15900353a8d7cc7c6fe55abf2bb30d06e4a69d31 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 6 Aug 2024 13:55:47 -0400 Subject: [PATCH 3/5] Trigger check-format workflow on push and merge groups --- .github/workflows/check-format.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/check-format.yml b/.github/workflows/check-format.yml index 6f91f5b..0739ce0 100644 --- a/.github/workflows/check-format.yml +++ b/.github/workflows/check-format.yml @@ -1,7 +1,9 @@ name: Files on: + merge_group: pull_request: + push: { branches: [main] } jobs: check-filenames: From e326c1d0eb426eceb5467d43dad87f6b8e58bc34 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 6 Aug 2024 14:23:01 -0400 Subject: [PATCH 4/5] Upgrade to Docsy v0.10.0-22-g2295188 --- package.json | 1 + themes/docsy | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index e0e20c2..7a899c0 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "_diff:check": "git diff --name-only --exit-code", "_filename-error": "echo 'ERROR: the following files violate naming conventions; fix using: `npm run fix:filenames`'; echo; npm run -s _ls-bad-filenames; exit 1", "_filenames-to-kebab-case": "find assets content -name '*_*' ! -name '[_.]*' -exec sh -c 'mv \"$1\" \"${1//_/-}\"' _ {} \\;", + "_get:no": "echo SKIPPING get operation", "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}", "_hugo-dev": "npm run _hugo -- -e dev -DFE", "_hugo": "hugo --cleanDestinationDir", diff --git a/themes/docsy b/themes/docsy index 309da20..2295188 160000 --- a/themes/docsy +++ b/themes/docsy @@ -1 +1 @@ -Subproject commit 309da207e5deeda762348bfd0cc32367c5565a1e +Subproject commit 2295188b164c34d7039e77fe537ee469d69085d9 From b46dc5cdad6fa61730ea77931fec9298f3ee84f1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 7 Aug 2024 19:13:55 -0400 Subject: [PATCH 5/5] Update NPM packages, including Hugo to 0.131.0 --- package.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/package.json b/package.json index 7a899c0..de3aecd 100644 --- a/package.json +++ b/package.json @@ -41,15 +41,15 @@ "update:pkgs": "npx npm-check-updates -u" }, "devDependencies": { - "autoprefixer": "^10.4.19", - "cspell": "^8.8.4", - "hugo-extended": "0.127.0", + "autoprefixer": "^10.4.20", + "cspell": "^8.13.1", + "hugo-extended": "0.131.0", "postcss-cli": "^11.0.0", - "prettier": "^3.3.1" + "prettier": "^3.3.3" }, "optionalDependencies": { - "netlify-cli": "^17.26.1", - "npm-check-updates": "^16.14.20" + "netlify-cli": "^17.33.6", + "npm-check-updates": "^17.0.5" }, "enginesComment": "Ensure that engines.node value stays consistent with the project's .nvmrc", "engines": {