myDocsy – DEV Test Content

Docs: Attachments

Mon, 01 Jan 0001 00:00:00 +0000

Shortcode to show a list of downloadable page resources resp. files in a folder.

Parameter	Default	Description
title	Attachments	The title of the box with the attachments. (The default value is the language specific variable `sc_attachments`.)
icon	fas fa-paperclip	Code for FontAwesome icon left from the title.
folder		If empty the page resources are used for the file list. If set a specific folder relativ to the current page can be used for generating a file list.
recursive	true	If true als files in subfolders will be found (only if the parameter `folder` is used).
exclude	.md,.markdown	Exclude Files with specific extenstion. By default markdown files are excluded, because they get renderd to an html file.
filter	.	RegEx filter on the filename relativ to the current page.
match	**	Glob pattern for filtering page resources.
class	td-max-width-on-larger-screens	Additional HTML class for the `<div>` containing the box with the attachments. The default value ensures that the box is the same width as other typical content.
num_prec	1	Parameter for formating file size: Number of decimal places
num_fmt	- , .	Parameter for formating file size (see Hugo docs).
num_fmt_del	" " (=blank)	Corresponding delimiter for parameter for formating file size (see Hugo docs).
empty_list	No attachments found.	Shown message if file list is empty.
show_folder	false	Option to show also the relative file path, when paramter `folder` is used.

Pure version without any parameter

The pure shortcode {{< attachments />}} displays all page resources of a page bundle. As visible Text for the links the resource parameter title is used. Default title value is the filename (relative to the owning page). Can be set in front matter. If set, also the resource parameter params.description get displayed under the link. All the resource parameter can be set by corresponding page’s front matter.

This is the front matter of the current page:

title: "Attachments"
linkTitle: "Testing Shortcode Attachments"
weight: 1
icon: fas fa-paperclip
tags: ["Shortcode", "Attachments"]
projects: ["Docsy"]
description: >
    Testing Shortcode Attachments
resources:
- src: '**.pdf'
  name: pdf-file-name-:counter
  title: pdf-file-title-:counter
  params:
    description: "This ist the description of all PDF files."

Attachments

attachments/crow.jpeg (16.6 kB)
attachments/data.csv (0.0 Byte)
attachments/document.doc (0.0 Byte)
attachments/open-office.odt (0.0 Byte)
attachments/song.mp3 (0.0 Byte)
attachments/video.mp4 (0.0 Byte)
crow.jpg (16.6 kB)
files/crow.JPG (16.6 kB)
files/data.json (0.0 Byte)
files/document.doc (0.0 Byte)
files/excel.xlsx (0.0 Byte)
files/file-1.txt (0.0 Byte)
files/goldmark-file.goldmark (0.0 Byte)
files/htm-file.htm (0.0 Byte)
files/html-file.html (0.0 Byte)
files/music.mp3 (0.0 Byte)
files/subfolder/audio.wav (0.0 Byte)
files/TestFile.JPG (16.6 kB)
pdf-file-title-1 (255.3 kB) This ist the description of all PDF files.
pdf-file-title-2 (0.0 Byte) This ist the description of all PDF files.
pdf-file-title-3 (0.0 Byte) This ist the description of all PDF files.
pdf-file-title-4 (8.3 kB) This ist the description of all PDF files.
pdf-file-title-5 (488.9 kB) This ist the description of all PDF files.
screenshot.png (1.1 MB)

Pure version with inner content

Also a inner content will be shown within the attachments box:

{{< attachments >}}
#### An inner Headline

Some inner text.
{{< /attachments >}}

Attachments

attachments/crow.jpeg (16.6 kB)
attachments/data.csv (0.0 Byte)
attachments/document.doc (0.0 Byte)
attachments/open-office.odt (0.0 Byte)
attachments/song.mp3 (0.0 Byte)
attachments/video.mp4 (0.0 Byte)
crow.jpg (16.6 kB)
files/crow.JPG (16.6 kB)
files/data.json (0.0 Byte)
files/document.doc (0.0 Byte)
files/excel.xlsx (0.0 Byte)
files/file-1.txt (0.0 Byte)
files/goldmark-file.goldmark (0.0 Byte)
files/htm-file.htm (0.0 Byte)
files/html-file.html (0.0 Byte)
files/music.mp3 (0.0 Byte)
files/subfolder/audio.wav (0.0 Byte)
files/TestFile.JPG (16.6 kB)
pdf-file-title-1 (255.3 kB) This ist the description of all PDF files.
pdf-file-title-2 (0.0 Byte) This ist the description of all PDF files.
pdf-file-title-3 (0.0 Byte) This ist the description of all PDF files.
pdf-file-title-4 (8.3 kB) This ist the description of all PDF files.
pdf-file-title-5 (488.9 kB) This ist the description of all PDF files.
screenshot.png (1.1 MB)

An inner Headline

Some inner text.

Using spezific Folder

Especially for none page bundles (not index.md or _index.md) it is also possible to set a specific subfolder for attachments::

{{< attachments folder="files" title="Files in folder" />}}

Files in folder

The resulting file list can be filtered by the options filter (by using RegEx on the filename relative to the current page).

{{< attachments title="Filtered page resources for jpg files" filter=".+\.(?i)(jpg|jpeg)$" />}}

Filtered page resources for jpg files

{{< attachments folder="./" title="Filtered all files in base folder for 'doc'" filter="doc" >}}
Also the file `document.pdf` get listed, because it begins with "doc".
{{< /attachments >}}

Filtered all files in base folder for 'doc'

Also the file document.pdf get listed, because it begins with “doc”.

If displaying page resources alternatively the parameter match can get used as file list filter. But Glob pattern has to be used and the name of the page resource instead of the file name get filtered!

{{< attachments title="Filtered page resources for 'files/*'" match="files/*" />}}

Filtered page resources for 'files/*'

All files in this test content

{{< attachments folder="./" title="All files" exclude="." show_folder=true />}}

All files

Docs: Manual Link

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Getting Started

Mon, 30 Jul 2018 00:00:00 +0000

Prerequisites and installation

Use our Docker image

We provide a Docker image that you can use to run and test your Docsy site locally, without having to install all Docsy’s dependencies.

You can see how to get started with this approach by following our Docker Quickstart tutorial. If you don’t want to use Docker, follow the instructions below to install Hugo and PostCSS.

Install Hugo

You need a recent extended version (we recommend version 0.75.0 or later) of Hugo 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; you may need to scroll down the list of releases to see it.

For comprehensive Hugo documentation, see gohugo.io.

Linux

Be careful using sudo apt-get install hugo, as it doesn’t get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

If you’ve already installed Hugo, check your version:

hugo version

If the result is v0.75 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. The following shows you how to install Hugo from the release page:

Go to the Hugo releases page.
In the most recent release, scroll down until you find a list of Extended versions.
Download the latest extended version (hugo_extended_0.5X_Linux-64bit.tar.gz).
Create a new directory:
```
mkdir hugo
```
Extract the files you downloaded to hugo.
Switch to your new directory:
```
cd hugo
```
Install Hugo:
```
sudo install hugo /usr/bin    
```

macOS

Install Hugo using Brew.

As an `npm` module

You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:

npm install hugo-extended --save-dev

See the hugo-bin documentation for usage details.

Install PostCSS

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS 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 autoprefixer
sudo npm install -D postcss-cli

Starting in version 8 of postcss-cli, you must also separately install postcss:

sudo npm install -D postcss

Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.

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. 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, so it’s easy to keep up to date.
Build your own site using the Docsy theme. Specify the Docsy theme like any other Hugo theme 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: Copy the Docsy example site

The Example Site 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 copy the Example Site either by:

Using the GitHub UI

This is the simplest approach, as the Docsy example site repo is a template repository. To create your own copy of the Docsy example site repo:

Go to the repo page and click Use this template.
Type your chosen name for your new repository in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you now have a Docsy site repo!
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):
```
 git clone --recurse-submodules --depth 1 https://github.com/my/example.git
 
```

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 (see the known issues on MacOS). 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:

Make a local working copy of the example site directly using git clone:
```
git clone https://github.com/google/docsy-example.git
```
Switch to the root of the cloned project, for example:
```
 cd docsy-example
```
Get local copies of the project submodules so you can build and run your site locally:
```
 git submodule update --init --recursive
```
Build your site:
```
 hugo server
```
Preview your site in your browser at: http://localhost:1313/. You can use Ctrl + c to stop the Hugo server whenever you like. See the known issues on MacOS.
Now that you have a site running, you can push it to a new repository:
1. Create a new repository in GitHub 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.
2. Configure origin 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
```
3. Verify that your remote is configured correctly by running:
```
  git remote -v
```
4. 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 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 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.

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.

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

If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:

git submodule update --init --recursive

For more information, see Theme Components on the Hugo 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/. See the known issues on MacOS.

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 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.

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. To disable this 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. Or choose another search option.

Known issues

MacOS

Errors: `too many open files` or `fatal error: pipe failed`

By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications, you might receive one of the following errors when you run hugo server to preview your site locally:

POSTCSS v7 and earlier:

ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files

POSTCSS v8 and later:
```
fatal error: pipe failed
```

Workaround

To temporarily allow more open files:

View your current settings by running:
```
sudo launchctl limit maxfiles
```
Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can set choose to set lower soft (65535) and hard (200000) limits.
```
sudo launchctl limit maxfiles 65535 200000
ulimit -n 65535
sudo sysctl -w kern.maxfiles=200000
sudo sysctl -w kern.maxfilesperproc=65535
```

Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.

What’s next?

Add content and customize your site
Get some ideas from our Example Site and other Examples.
Publish your site.

Docs: Multi-language Support

Mon, 01 Jan 0001 00:00:00 +0000

If you’d like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.

Content and configuration

To add content in multiple languages, you first need to define the available languages in a languages section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:

contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
...
[languages]
[languages.en]
title = "Docsy"
description = "Docsy does docs"
languageName ="English"
# Weight used for sorting.
weight = 1
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"

Any setting not defined in a [languages] block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be content/en unless the user selects the Norwegian language option.

Once you’ve updated your site config, you create a content root directory for each language version in your source repo, such as content/en for English text, and add your content as usual. See the Hugo Docs on multi-language support for more information.

Tip

If there’s any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don’t need to move it if you add another language.

For adding multiple language versions of other site elements such as button text, see the internationalization bundles section below.

Selecting a language

If you configure more than one language in config.toml, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.

Internationalization bundles

All UI strings (text for buttons etc.) are bundled inside /i18n in the theme, with a .toml file for each language.

If your chosen language isn’t currently in the theme and you create your own .toml file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of en.toml called jp.toml), we recommend you do this in the theme rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project’s /i18n folder.

Hugo Tip

Run hugo server --i18n-warnings when doing translation work, as it will give you warnings on what strings are missing.

Docs: Previews and Deployment

Mon, 01 Jan 0001 00:00:00 +0000

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. Hugo also makes it easy to deploy your site locally for quick previews of your content.

Serving your site locally

Depending on your deployment choice you may want to serve your site locally during development to preview content changes. To serve your site locally:

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
```
Note

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
```
Ensure you have the tools described in Prerequisites and installation installed on your local machine, including postcss-cli (you’ll need it to generate the site resources the first time you run the server).
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.

Deployment with Netlify

We recommend using Netlify as a particularly simple way to serve your site from your Git provider (GitHub, GitLab, or BitBucket), with continuous deployment, previews of the generated site when you or your users create pull requests against the doc repo, and more. Netlify is free to use for Open Source projects, with premium tiers if you require greater support.

Before deploying with Netlify, make sure that you’ve pushed your site source to your chosen GitHub (or other provider) repo, following any setup instructions in Using the theme.

Then follow the instructions in Host on Netlify to set up a Netlify account (if you don’t have one already) and authorize access to your GitHub or other Git provider account. Once you’re logged in:

Click New site from Git.
Click your chosen Git provider, then choose your site repo from your list of repos.
In the Deploy settings page:
1. For your Build command, specify cd themes/docsy && git submodule update -f --init && cd ../.. && hugo. You need to specify this rather than just hugo so that Netlify can use the theme’s submodules.
2. Click Show advanced.
3. In the Advanced build settings section, click New variable.
4. Specify HUGO_VERSION as the Key for the new variable, and 0.53 or later as its Value.
5. (Optional) Click New variable again, and this time set HUGO_ENV to production. Do this if you want your site to be indexed by search engines. You must do this if you want to use a Google Custom Search Engine.
Click Deploy site.

Note

Netlify uses your site repo’s package.json file to install any JavaScript dependencies (like postcss) before building your site. If you haven’t just copied our example site’s version of this file, make sure that you’ve specified all our prerequisites.

For example, if you want to use a version of postcss-cli later than version 8.0.0, you need to ensure that your package.json also specifies postcss separately:

  "devDependencies": {
    "autoprefixer": "^9.8.6",
    "postcss-cli": "^8.0.0",
    "postcss": "^8.0.0"
  }

Alternatively, you can follow the same instructions but specify your Deploy settings in a netlify.toml file in your repo rather than in the Deploy settings page. You can see an example of this in the Docsy theme repo (though note that the build command here is a little unusual because the Docsy user guide is inside the theme repo).

If you have an existing deployment you can view and update the relevant information by selecting the site from your list of sites in Netlify, then clicking Site settings - Build and deploy. Ensure that Ubuntu Xenial 16.04 is selected in the Build image selection section - if you’re creating a new deployment this is used by default. You need to use this image to run the extended version of Hugo.

Docs: Examples

Mon, 01 Jan 0001 00:00:00 +0000

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:

Site	Repo (if public)
This Docsy documentation site	https://github.com/google/docsy
“Goldydocs” - a Docsy example site	https://github.com/google/docsy-example
https://www.kubeflow.org/	https://github.com/kubeflow/website
https://agones.dev/site/	https://github.com/GoogleCloudPlatform/agones/tree/master/site
https://googlecontainertools.github.io/kpt/	https://github.com/GoogleContainerTools/kpt/tree/master/docs
Navidrome Music Server	https://github.com/navidrome/website
https://docs.agilebase.co.uk/	https://github.com/okohll/abdocs
https://jvmperf.net/	https://github.com/cchesser/java-perf-workshop
gRPC	https://github.com/grpc/grpc.io

Customized Docsy examples

Example sites that include a moderate to high amount of customization:

Site	Repo (if public)
Knative	https://github.com/knative/docs and https://github.com/knative/website
Apache Airflow	https://github.com/apache/airflow-site/
Docsy Just Docs	https://github.com/LisaFC/justdocs
Thunderhead Engineering Product Support	https://gitlab.com/tecidev/support (private)
Kubernetes	https://github.com/kubernetes/website

Docs: Guidelines for Contribution to Docsy

Mon, 01 Jan 0001 00:00:00 +0000

Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better.

Contributing to Docsy

The Docsy theme itself lives in https://github.com/google/docsy.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Previewing your changes

As Docsy is a theme rather than a site, you can’t serve the theme directly to check your changes work. Instead use your updated local theme in a local copy of the Docsy example site (copy or make your changes in the themes/docsy directory) and preview from there. Alternatively, clone the Docsy theme repo and test your changes in a local copy of this site, as described below.

Community guidelines

This project follows Google’s Open Source Community Guidelines.

Creating issues

Alternatively, if there’s something you’d like to see in Docsy (or if you’ve found something that isn’t working the way you’d expect), but you’re not sure how to fix it yourself, please create an issue.

Contributing to these docs

This user guide is, like our example site, a Docsy site that uses the Hugo static site generator. We welcome updates to the docs!

We use Netlify to manage the deployment of the site and provide previews of doc updates. The instructions here assume you’re familiar with basic GitHub workflows.

Quick start with Netlify

Fork the Docsy repo on GitHub: this site’s files live in the userguide subdirectory.
Make your changes and send a pull request (PR).
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.)
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!
Click Details to the right of “Deploy preview ready” to see a preview of your updates.
Continue updating your doc and pushing your changes until you’re happy with the content.
When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

Click Edit this page in the top right hand corner of the page.
If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
Follow the rest of the Quick start with Netlify process above to make and preview your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

Follow the instructions in Getting started to install Hugo and any other tools you need.
Fork the 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.
```
git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
```
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.
```
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.
Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If there’s something you’d like to see in the docs, but you’re not sure how to fix it yourself, please create an issue in this repository. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

myDocsy – DEV Test Content

Docs: Attachments

Pure version without any parameter

Pure version with inner content

An inner Headline

Using spezific Folder

Using filter options

All files in this test content

Docs: Manual Link

Docs: Getting Started

Prerequisites and installation

Use our Docker image

Install Hugo

Linux

macOS

As an npm module

Install PostCSS

Using the theme

Option 1: Copy the Docsy example site

Using the GitHub UI

Using the command line

Option 2: Use the Docsy theme in your own site

Using the Docsy theme as a submodule

Cloning the Docsy theme to your project’s themes subdirectory

Preview your site

Basic site configuration

Internationalization

Search

Known issues

MacOS

Errors: too many open files or fatal error: pipe failed

Workaround

What’s next?

Docs: Multi-language Support

Content and configuration

Tip

Selecting a language

Internationalization bundles

Hugo Tip

Docs: Previews and Deployment

Serving your site locally

Note

Deployment with Netlify

Note

Docs: Examples

Docsy theme examples

Customized Docsy examples

Docs: Guidelines for Contribution to Docsy

Contributing to Docsy

Contributor License Agreement

Code reviews

Previewing your changes

Community guidelines

Creating issues

Contributing to these docs

Quick start with Netlify

Updating a single page

Previewing your changes locally

Creating an issue

As an `npm` module

Cloning the Docsy theme to your project’s `themes` subdirectory

Errors: `too many open files` or `fatal error: pipe failed`