Docsy 0.4.0 migration instructions and doc updates (#1074)

* Docsy 0.4.0 migration instructions and doc updates

* Also drop --recurse-submodules

* tiny fix

Co-authored-by: LisaFC <[email protected]>

Author: chalin

CHANGELOG.md

@@ -6,7 +6,42 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
 ## [0.4.0][] - next planned release (unpublished yet)
 
-TBC
+**Breaking changes**:
+
+- Docsy no longer uses git submodules for Bootstrap and FontAwesome. If your
+  project uses [Hugo Modules][], then this change doesn't impact you.
+
+  For projects with [other Docsy setups][], use the NPM packages of Bootstrap
+  and FontAwesome. Migrate your site by following these steps (execute commands
+  from your project's root directory):
+
+   1. Update Docsy to 0.4.0.
+   2. Delete obsolete Docsy Git submodules:
+      ```console
+      $ rm -Rf themes/docsy/assets/vendor
+      ```
+   3. Get Docsy dependencies:
+      ```console
+      $ (cd themes/docsy && npm install)
+      ```
+   4. (Optional) If your site project uses NPM, consider getting Docsy
+      dependencies via a `prepare` script, for example:
+      ```json
+      {
+        "name": "my-website",
+        "scripts": {
+          "get:submodule": "git submodule update --init --depth 1",
+          "_prepare:docsy": "cd themes/docsy && npm install",
+          "prepare": "npm run get:submodule && npm run _prepare:docsy",
+          "...": "..."
+        },
+        "...": "..."
+      }
+      ```
+   5. Proceed as usual to build or serve your site.
+
+[Hugo Modules]: https://www.docsy.dev/docs/get-started/docsy-as-module/
+[other Docsy setups]: https://www.docsy.dev/docs/get-started/other-options/
 
 ## [0.3.0][]
 

userguide/content/en/docs/Contribution guidelines/_index.md

@@ -1,9 +1,7 @@
 ---
-title: "Contribution Guidelines"
-linkTitle: "Contribution Guidelines"
+title: Contribution Guidelines
 weight: 9
-description: >
-  How to contribute to Docsy
+description: How to contribute to Docsy
 ---
 
 Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better.
@@ -54,15 +52,15 @@ We use [Netlify](https://www.netlify.com/) to manage the deployment of the site
 
 1. Fork the [Docsy repo](https://github.com/google/docsy) on GitHub: this site's files live in the `userguide` subdirectory.
 1. Make your changes and send a pull request (PR).
-1. If you're not yet ready for a review, add "WIP" to the PR name to indicate 
-  it's a work in progress. (**Don't** add the Hugo property 
-  "draft = true" to the page front matter, because that prevents the 
+1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
+  it's a work in progress. (**Don't** add the Hugo property
+  "draft = true" to the page front matter, because that prevents the
   auto-deployment of the content preview described in the next point.)
 1. Wait for the automated PR workflow to do some checks. When it's ready,
   you should see a comment like this: **deploy/netlify — Deploy preview ready!**
 1. Click **Details** to the right of "Deploy preview ready" to see a preview
   of your updates.
-1. Continue updating your doc and pushing your changes until you're happy with 
+1. Continue updating your doc and pushing your changes until you're happy with
   the content.
 1. When you're ready for a review, add a comment to the PR, and remove any
   "WIP" markers.
@@ -81,22 +79,22 @@ If you've just spotted something you'd like to change while using the docs, Docs
 If you want to run your own local Hugo server to preview your changes as you work:
 
 1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need.
-1. Fork the [Docsy](https://github.com/google/docsy) repo into your own project, then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
+1. Fork the [Docsy](https://github.com/google/docsy) repo into your own project, then create a local copy using `git clone`:
 
-    ```
-    git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
+    ```sh
+    git clone https://github.com/google/docsy.git
     ```
 
 1. Change to the `userguide` directory and run the following Hugo command to build the site and start the Hugo server.
    Note that you need the `themesDir` flag because the site files are inside the theme repo.
 
-    ```
+    ```sh
     cd userguide
     hugo server --themesDir ../..
     ```
-    
+
     By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
-   
+
 1. Continue with the usual GitHub workflow to edit files, commit them, push the
   changes up to your fork, and create a pull request.
 
@@ -111,7 +109,7 @@ locally with Docker, without installing any additional dependencies.
 
       ```bash
       docker build -t docsy/user-guide .
-      ``` 
+      ```
 
   1.  Run the container, mounting the repository as a shared volume:
 

userguide/content/en/docs/Deployment/_index.md

@@ -1,9 +1,7 @@
 ---
-title: "Previews and Deployment"
-linkTitle: "Previews and Deployment"
+title: Previews and Deployment
 weight: 7
-description: >
-  Deploying your Docsy site.
+description: Deploying your Docsy site.
 ---
 
 There are multiple possible options for deploying a Hugo site, including Netlify, Firebase Hosting, Bitbucket with Aerobatic, and more; you can read about them all in [Hosting and Deployment](https://gohugo.io/hosting-and-deployment/). Hugo also makes it easy to deploy your site locally for quick previews of your content.
@@ -12,20 +10,10 @@ There are multiple possible options for deploying a Hugo site, including Netlify
 
 Depending on your deployment choice you may want to serve your site locally during development to preview content changes. To serve your site locally:
 
-1. Ensure you have an up to date local copy of your site files cloned from your repo. Don't forget to use `--recurse-submodules` or you won't pull down some of the code you need to generate a working site.
-
-    ```
-    git clone --recurse-submodules --depth 1 https://github.com/my/example.git
-    ```
-
-    {{% alert title="Note" color="primary" %}}
-If you've just added the theme as a submodule in a local version of your site and haven't committed it to a repo yet,  you must get local copies of the theme's own submodules before serving your site.
-
-    git submodule update --init --recursive
-    {{% /alert %}}
+1. Ensure you have an up to date local copy of your site files cloned from your repo.
 
 1. Ensure you have the tools described in [Prerequisites and installation](/docs/get-started/docsy-as-module/installation-prerequisites) installed on your local machine, including `postcss-cli` (you'll need it to generate the site resources the first time you run the server).
-1. Run the `hugo server` command in your site root. By default your site will be available at http://localhost:1313/.
+1. Run the `hugo server` command in your site root. By default your site will be available at <http://localhost:1313>.
 
 Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. If you have more than one local git branch, when you switch between git branches the local website reflects the files in the current branch.
 

userguide/content/en/docs/Get started/_index.md

@@ -1,13 +1,12 @@
 
 ---
-title: "Get started"
-linkTitle: "Get started"
+title: Get started
 weight: 2
-aliases:
-    - /docs/getting-started/
+aliases: [/docs/getting-started/]
 date: 2018-07-30
-description: >
-  Learn how to get started with Docsy, including the available options for installing and using the Docsy theme.
+description:
+  Learn how to get started with Docsy, including the available options for
+  installing and using the Docsy theme.
 ---
 
 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.

userguide/content/en/docs/Get started/other-options.md

@@ -1,9 +1,8 @@
 ---
-title: "Other setup options"
-linkTitle: "Other setup options"
+title: Other setup options
 date: 2021-12-08T09:22:27+01:00
 weight: 2
-description: >
+description:
   Create a new Docsy site with Docsy as a Git submodule or cloned theme
 ---
 
@@ -15,9 +14,9 @@ This guide provides instructions for both these options, along with common prere
 
 ## Prerequisites and installation
 
-### Install Hugo 
+### Install Hugo
 
-You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.73.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. 
+You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.73.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it.
 
 For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/).
 
@@ -30,8 +29,9 @@ If you've already installed Hugo, check your version:
 ```
 hugo version
 ```
+
 If the result is `v0.73` or earlier, or if you don't see `Extended`, you'll need to install the latest version. You can see a complete list of Linux installation options in [Install Hugo](https://gohugo.io/getting-started/installing/#linux). The following shows you how to install Hugo from the release page:
-    
+
 1.  Go to the [Hugo releases](https://github.com/gohugoio/hugo/releases) page.
 2.  In the most recent release, scroll down until you find a list of
     **Extended** versions.
@@ -48,7 +48,7 @@ If the result is `v0.73` or earlier, or if you don't see `Extended`, you'll need
 
 7.  Install Hugo:
 
-        sudo install hugo /usr/bin    
+        sudo install hugo /usr/bin
 
 #### On macOS
 
@@ -81,42 +81,64 @@ npm install -D postcss
 
 Note that versions of `PostCSS` later than 5.0.1 will not load `autoprefixer` if installed [globally](https://flaviocopes.com/npm-packages-local-global/), you must use a local install.
 
-## Other option 1: Use the theme as a submodule
+## Option 1: Docsy as a Git submodule
 
-To create a new Hugo site project and then add the Docsy theme as a submodule, run the following commands from your project's root directory.
+To create a **new site** and add the Docsy theme as a Git submodule, run the
+following commands:
 
-```shell
-hugo new site myproject
-cd myproject
-git init
-git submodule add https://github.com/google/docsy.git themes/docsy
-echo 'theme = "docsy"' >> config.toml
-git submodule update --init --recursive
-```
+ 1. Create the site:
 
-To add the Docsy theme to an existing site, run the following commands from your project's root directory:
+    ```shell
+    hugo new site myproject
+    cd myproject
+    git init
+    ```
 
-```
-git submodule add https://github.com/google/docsy.git themes/docsy
+ 2. Add Docsy as a theme via a Git submodule:
+
+    ```shell
+    git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy
+    echo 'theme = "docsy"' >> config.toml
+    ```
+
+ 3. Install postCSS as [instructed earlier](install-postcss).
+
+ 4. Get Docsy dependencies:
+
+    ```shell
+    (cd themes/docsy && npm install)
+    ```
+
+ 5. Build or serve your new site using the usual Hugo commands, for example:
+
+    ```shell
+    hugo serve
+    ```
+
+To add the Docsy theme to an **existing site**, run the following commands from your
+project's root directory:
+
+```sh
+git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy
 echo 'theme = "docsy"' >> config.toml
-git submodule update --init --recursive
+(cd themes/docsy && npm install)
 ```
 
-## Other option 2: Clone the Docsy theme
+## Option 2: Clone the Docsy theme
 
-If you don't want to use a submodules (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 theme into your project's `themes` subdirectory.
+If you don't want to use a submodules (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 theme
+into your project's `themes` subdirectory.
 
-To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory:
+To clone Docsy into your project's `theme` folder, run the following commands
+from your project's root directory:
 
-```
+```sh
 cd themes
 git clone https://github.com/google/docsy
-```
-
-If you want to build and/or serve your site [locally](/docs/deployment/#serving-your-site-locally), you also need to get local copies of the theme’s own submodules:
-
-```
-git submodule update --init --recursive
+cd docsy
+npm install
 ```
 
 For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site.
@@ -129,8 +151,8 @@ To build and preview your site locally:
 cd myproject
 hugo server
 ```
-    
-By default, your site will be available at http://localhost:1313/. [See the known issues on MacOS](/docs/get-started/known_issues/#macos).
+
+By default, your site will be available at <http://localhost:1313>. [See the known issues on MacOS](/docs/get-started/known_issues/#macos).
 
 You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you’re missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in [Basic site configuration](/docs/get-started/basic-configuration/) - we recommend copying the example site configuration even if you’re creating a site from scratch as it provides defaults for many required configuration parameters.