diff options
Diffstat (limited to 'themes/docsy/userguide/content/en/docs/Getting started')
| -rwxr-xr-x | themes/docsy/userguide/content/en/docs/Getting started/_index.md | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/themes/docsy/userguide/content/en/docs/Getting started/_index.md b/themes/docsy/userguide/content/en/docs/Getting started/_index.md new file mode 100755 index 0000000..52f1c3d --- /dev/null +++ b/themes/docsy/userguide/content/en/docs/Getting started/_index.md @@ -0,0 +1,267 @@ + +--- +title: "Getting Started" +linkTitle: "Getting Started" +weight: 2 +date: 2018-07-30 +description: > + This page tells you how to get started with the Docsy theme, including installation and basic configuration. +--- + + +## Prerequisites and installation + +### Install Hugo + +You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.53 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/). + +#### Linux + +Do **not** use `sudo apt-get install hugo`, as it currently doesn't get you the `extended` version. + +If you've already installed Hugo, check your version: + +``` +hugo version +``` +If the result is `v0.52` or earlier, or if you don't see `Extended`, you'll need to install the latest version. + +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. +3. Download the latest extended version (`hugo_extended_0.5X_Linux-64bit.tar.gz`). +4. Create a new directory: + + mkdir hugo + +5. Extract the files you downloaded to `hugo`. + +6. Switch to your new directory: + + cd hugo + +7. Install Hugo: + + sudo install hugo /usr/bin + +#### macOS + +Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos). + +### Install PostCSS + +To build or update your site's CSS resources, you also need [`PostCSS`](https://postcss.org/) to create the final assets. If you need to install it, you must have a recent version of [NodeJS](https://nodejs.org/en/) installed on your machine so you can use `npm`, the Node package manager. By default `npm` installs tools under the directory where you run `npm install`: + +``` +sudo npm install -D --save autoprefixer +sudo npm install -D --save postcss-cli +``` + +You can also install these tools globally on your computer: + +```bash +sudo npm install -g postcss-cli +sudo npm install -g autoprefixer +``` + +You can find out more about the pros and cons of local and global package installation in [npm Global or Local Packages](https://flaviocopes.com/npm-packages-local-global/). + +## Using the theme + +To use the Docsy Hugo theme, you have a couple of options: + +* **Copy and edit the source for the [Docsy example site](https://github.com/google/docsy-example).** This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site uses Docsy as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so it's easy to [keep up to date](#keeping-the-theme-up-to-date). +* **Build your own site using the Docsy theme.** Specify the [Docsy theme](https://github.com/google/docsy) like any other [Hugo theme](https://gohugo.io/themes/) when creating or updating your site. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. + +### Option 1: Clone the Docsy example site + +The [Example Site](https://example.docsy.dev) gives you a good starting point for building your docs site and is +pre-configured to use the Docsy theme as a Git submodule. You can clone the Example Site either by: + +* [Using the GitHub UI](#using-the-github-ui) +* [Using the command line](#using-the-command-line) + +#### Using the GitHub UI + +<!--This is the simplest approach, as the Docsy example site repo is a [template repository](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/). To create your own copy of the Docsy example site repo: + +1. Go to the [repo page](https://github.com/google/docsy-example) and click **Use this template**. + +1. Type your chosen name for your new repository in the **Repository name** field. You can also add an optional **Description**. + +1. Click **Create repository from template** to create your new repository. Congratulations, you now have a Docsy site repo! + +1. To test your copied site locally with Hugo, or make local edits, you'll also need to make a local copy of your new repository. To do this, use `git clone`, replacing `https://github.com/my/example.git` with your repo's web URL (don't forget to use `--recurse-submodules` or you won't pull down some of the code you need to generate a working site): + + <pre> + git clone --recurse-submodules --depth 1 <em>https://github.com/my/example.git</em> + </pre> + +You can now edit your local versions of the site's source files. To preview your site, go to your site root directory and run `hugo server`. By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use `git push`.--> + +Note that the following approach [forks](https://help.github.com/en/articles/fork-a-repo) our repo and so creates a connection in GitHub between your project repo and the Docsy example site project repo - our project will be the "upstream" version of your site project: + +1. In the [the Docsy example site's GitHub repo](https://github.com/google/docsy-example), click **Fork** and follow the prompts. +1. Rename your new fork: + 1. Click **Settings**, and type a new name in the **Repository name** field. + 1. Click **Rename** to save your changes. +1. Get the web URL for cloning your site repo by clicking **Clone or download** on its main repo page. +1. Make your own local working copy of your repo using `git clone`, replacing `https://github.com/my/example.git` with your repo's web URL: + + <pre> + git clone --recurse-submodules --depth 1 <em>https://github.com/my/example.git</em> + </pre> + +You can now edit your local versions of the site's source files. To preview your site, go to your site root directory and run `hugo server`. By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use `git push`. + + +#### Using the command line + +To copy the example site: + +1. Make a local working copy of the example site directly using `git clone`: + + git clone https://github.com/google/docsy-example.git + +1. Switch to the root of the cloned project, for example: + + cd docsy-example + +1. Get local copies of the project submodules so you can build and run your site locally: + + git submodule update --init --recursive + +1. Build your site: + + hugo server + +1. Preview your site in your browser at: http://localhost:1313/. You can use `Ctrl + c` to stop the Hugo server whenever you like. + +1. Now that you have a site running, you can push it to a new repository: + + 1. [Create a new repository in GitHub](https://help.github.com/en/articles/create-a-repo) + for your site with your chosen repo name. For clarity you may also want to rename the root + directory (`docsy-example`) of your working copy to match, though everything will still + work even if you don't. + + 1. Configure + [`origin`](https://help.github.com/en/articles/configuring-a-remote-for-a-fork) + in your project. From your site's root directory, set the URL for `origin` to your new + repo (otherwise you'll be trying to push changes to `google/docsy` rather than to your repo): + + git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git + + + 1. Verify that your remote is configured correctly by running: + + git remote -v + + + 1. Push your Docsy site to your repository: + + git push -u origin master + +### Option 2: Use the Docsy theme in your own site + +Specify the [Docsy theme](https://github.com/google/docsy) like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you'll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project's `themes` subdirectory. + +Whichever approach you use, for simplicity we recommend copying and editing our [example site configuration](#configuring-your-site) for your project, or you may get Hugo errors for missing parameters and values when you try to build your site. + +#### Using the Docsy theme as a submodule + +Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project +always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in +your repo that may result in merge conflicts when you try to update it. This is the approach used by our +[example project](https://github.com/google/docsy-example). + + +To create a new Hugo site project and then add the Docs theme as a submodule, 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 +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +To add the Docsy theme to an existing site, run the following commands from your project's root directory: + +``` +git submodule add https://github.com/google/docsy.git themes/docsy +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +#### Cloning the Docsy theme to 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. + + + + +To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory: + +``` +cd themes +git clone https://github.com/google/docsy +``` + +For more information, see [Install and Use Themes](https://gohugo.io/themes/installing-and-using-themes/#install-a-single-theme) on the [Hugo](https://gohugo.io) site. + +#### Preview your site + +To build and preview your site locally: + +``` +cd myproject +hugo server +``` + +By default, your site will be available at http://localhost:1313/. + +## Basic site configuration + +Site-wide configuration details and parameters are defined in your project's `config.toml` file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`config.toml` in the example project](https://github.com/google/docsy-example/blob/master/config.toml) for how to add this information. **We recommend copying this `config.toml` and editing it even if you're just using the theme and not copying the entire Docsy example site**. + +The Docsy example site comes with some defaults you may want to remove or customize straight away: + +### Internationalization + +The Docsy example site supports content in English and Norwegian. You can find out more about how Docsy supports multi-language content in [Multi-language support](/docs/language/_index.md). + +If you don't intend to translate your site to Norwegian, you can remove the language switcher by removing the following lines from `config.toml`: + +``` +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +``` + +To remove the translated source files, delete the `docsy-example/content/no` directory. + +### Search + +By default, the Docsy example site uses its own [Google Custom Search Engine](https://cse.google.com/cse/all). To disable site search, delete or comment out the following lines: + +``` +# Google Custom Search Engine ID. Remove or comment out to disable search. +gcs_engine_id = "011737558837375720776:fsdu1nryfng" +``` + +To use your own Custom Search Engine, replace the value in the `gcs_engine_id` with the ID of your own search engine. + + +## What's next? + +* [Add content and customize your site](/docs/adding-content/) +* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/). +* [Publish your site](/docs/deployment/). + + + |