theme: Switch to docsy theme

3 files changed, 105 insertions, 0 deletions

diff --git a/themes/docsy/userguide/content/en/docs/Best practices/_index.md b/themes/docsy/userguide/content/en/docs/Best practices/_index.md
new file mode 100644
index 0000000..fb1ee78
--- /dev/null
+++ b/themes/docsy/userguide/content/en/docs/Best practices/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Best Practices"
+weight: 9
+description: >
+  Optional guidance and recommendations about organizing, authoring, and managing your technical documentation.
+---
+
+Use this section to learn about some of the best practices around creating technical documentation with Docsy.
diff --git a/themes/docsy/userguide/content/en/docs/Best practices/organizing-content.md b/themes/docsy/userguide/content/en/docs/Best practices/organizing-content.md
new file mode 100644
index 0000000..3a2ba3f
--- /dev/null
+++ b/themes/docsy/userguide/content/en/docs/Best practices/organizing-content.md
@@ -0,0 +1,56 @@
+---
+title: "Organizing Your Content"
+linkTitle: "Organizing Your Content"
+weight: 9
+description: >
+  Optional guidance and recommendations on how to organize your documentation site.
+---
+
+If you have a look at our [Example Site](https://example.docsy.dev/about/), you'll see that we've organized 
+the Documentation section into a number of subsections, each with some recommendations about what you might put 
+in that section.
+
+## Do I need to use this structure?
+
+Absolutely not! The site structure in the Example Site was created to meet the needs of large docsets for large
+products with lots of features, potential tasks, and reference elements. For a simpler docset (like this one!),
+it's fine to just structure your docs around specific features that your users need to know about.  Even for larger
+documentation sets, you may find that the structure isn't useful "as is", or that you don't need to use all the 
+section types. 
+
+We do recommend that (as we've done here) you provide at least:
+
+* An **Overview** of the product (either on the docs landing page or a separate Overview page) that tells the user 
+  why they should be interested in your project.
+* A **Getting Started** page.
+* Some **Examples**.
+
+You may also want to create some tasks/how-tos for your project's features. Feel free to copy this Docsy user guide 
+site or even just the docs section instead if you like this simpler structure better. 
+
+{{% alert title="Tip" %}}
+If you want to copy this guide, be aware that its [source files](https://github.com/google/docsy/tree/master/userguide) are *inside* the Docsy theme repo, and so it doesn't have its own `themes/` directory: instead, we run `hugo server --themesDir ../..` to use Docsy from its parent directory. You may want to either copy the site and [add a `themes/` directory with Docsy](/docs/getting-started/#option-2-use-the-docsy-theme-in-your-own-site), or just copy the `docs/` folder into your existing site's content root.
+{{% /alert %}}
+
+[Learn more about how Hugo and Docsy use folders and other files to organize your site](/docs/adding-content/content/#organizing-your-documentation).
+
+## Why this structure?
+
+We based the Example Site structure on our own experiences creating (and using) large documentation sets for
+different types of project and on user research carried out on some of our bigger sites. In user studies we saw that 
+users cared most about and immediately looked for a Get Started or Getting Started section 
+(so they could, well, get started), and some examples to explore and copy, so we made those into prominent top-level doc 
+sections in our site. Users also wanted to find "recipes" that they could easily look up to perform specific tasks and 
+put together to create their own applications or projects, so we suggest that you add this kind of content as Tasks. 
+Other content types such as conceptual docs, reference docs, and end-to-end tutorials are less important for all doc sets, 
+particularly for smaller projects. We emphasize in our Example Site that these sections are optional.
+
+We hope to improve the Example Site structure further as we learn more about how users interact with technical 
+documentation, particularly for Open Source projects.
+
+## Writing style guide
+
+This guide and the example site just address how to organize your documentation content into pages and sections. For some g
+uidance on how to organize and write the content in each page, we recommend the 
+[Google Developer Documentation Style Guide](https://developers.google.com/style/), particularly the 
+[Style Guide Highlights](https://developers.google.com/style/highlights).
diff --git a/themes/docsy/userguide/content/en/docs/Best practices/site-guidance.md b/themes/docsy/userguide/content/en/docs/Best practices/site-guidance.md
new file mode 100644
index 0000000..ff8a663
--- /dev/null
+++ b/themes/docsy/userguide/content/en/docs/Best practices/site-guidance.md
@@ -0,0 +1,41 @@
+---
+title: "Hugo Content Tips"
+linkTitle: "Hugo Content Tips"
+weight: 9
+description: >
+  Tips for authoring content for your Docsy-themed Hugo site.
+---
+
+Docsy is a theme for the [Hugo](https://gohugo.io/) static site 
+generator. If you're not already familiar with Hugo and, in particular, its version of Markdown, this page provides some 
+useful tips and potential gotchas for adding and editing content for your site. Feel free to add your own!
+
+## Nested lists
+
+Hugo currently uses the [Blackfriday](https://github.com/russross/blackfriday) Markdown processor, which can be 
+sensitive when it come to content that's deeply nested in a list. In particular, be aware that
+[this known issue](https://github.com/russross/blackfriday/issues/329) can surface if or when you have multiple authors and
+other contributors who might mix 'tabs' and 'spaces' when indenting lists, or fail to indent properly.
+
+An additional factor here is that because GitHub uses a different Markdown processor, GitHub markdown and the editor UI may
+render some nested lists properly, while Blackfriday might render that same content poorly. For example, the count in a
+numbered list might restart, or your nested content within a list is not indented 
+(shows as a peer element instead of a nested child element). You may want to recommend in your contribution guidelines
+([as we do](/docs/contribution-guidelines/#contributing-to-these-docs)) that contributors preview their content with Hugo
+(or use Netlify's preview feature for PRs if that's your chosen deployment tool) to ensure their content renders correctly
+with Blackfriday.
+
+{{% alert title="Tip" %}}
+[Per comments on the known issue](https://github.com/russross/blackfriday/issues/329#issuecomment-277602856), some
+users have found that using 4 spaces instead of a 'tab' results in consistent behavior. For example, consider
+configuring your local editor to use 4 spaces when the **Tab** key is pressed.
+{{% /alert %}}
+
+## Linking
+
+By default, regular relative URLs in links are left unchanged by Hugo (they're still relative links in your site's generated HTML), hence some hardcoded relative links like `[relative cross-link](../../peer-folder/sub-file.md)` might behave unexpectedly compared to how they work on your local file system. You may find it helpful to use some of Hugo's built-in [link shortcodes](https://gohugo.io/content-management/cross-references/#use-ref-and-relref) to avoid broken links in your generated site. For example a `{< ref "filename.md" >}` link in Hugo will actually
+find and automatically link to your file named `filename.md`. 
+
+Note, however, that `ref` and `relref` links don't work with `_index` or `index` files (for example, this site's [content landing page](`/docs/adding-content/`)): you'll need to use regular Markdown links to section landing or other index pages. Specify these links relative to the site's root URL, for example: `/docs/adding-content/`.
+
+[Learn more about linking](/docs/adding-content/content/#working-with-links).