Convert docs to docsy

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

site/themes/docsy/userguide/content/en/docs/Best practices/organizing-content.md

@@ -0,0 +1,55 @@
+---
+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 guidance 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).

site/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).