Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docsy 0.4.0 migration instructions and doc updates #1074

Merged
merged 3 commits into from
Jun 27, 2022
Merged

Docsy 0.4.0 migration instructions and doc updates #1074

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f104aa
Docsy 0.4.0 migration instructions and doc updates
chalin Jun 24, 2022
4fd3830
Also drop --recurse-submodules
chalin Jun 24, 2022
a7a0f57
tiny fix
LisaFC Jun 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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][]

Expand Down
28 changes: 13 additions & 15 deletions userguide/content/en/docs/Contribution guidelines/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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:

Expand Down
20 changes: 4 additions & 16 deletions userguide/content/en/docs/Deployment/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I simplified this because, IMHO, we shouldn't be telling folks how to clone their own repos -- in particular because we don't know the flags that they require.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works for me, the only reason we used to have to remind people to recurse into the submodules was because of FontAwesome and Bootstrap, we had a lot of users who cloned sites that didn't work because they were missing those submodules.


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.

Expand Down
11 changes: 5 additions & 6 deletions userguide/content/en/docs/Get started/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
88 changes: 55 additions & 33 deletions userguide/content/en/docs/Get started/other-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---

Expand All @@ -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/).

Expand All @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand Down