User guide: remove content related to Blackfriday (unsupported) (goog…

…le#1038)

Co-authored-by: LisaFC <[email protected]>

userguide/config.toml

@@ -28,13 +28,6 @@ home = [ "HTML" ]
 page = [ "HTML" ]
 section = [ "HTML", "RSS", "print"]
 
-## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
-[blackfriday]
-plainIDAnchors = true
-hrefTargetBlank = true
-angledQuotes = false
-latexDashes = true
-
 # Image processing configuration.
 [imaging]
 resampleFilter = "CatmullRom"

userguide/content/en/docs/Adding content/content.md

@@ -6,7 +6,7 @@ description: >
   Add different types of content to your Docsy site.
 ---
 
-So you've got a new Hugo website with Docsy, now it's time to add some content! This page tells you how to use the theme to add and structure your site content. 
+So you've got a new Hugo website with Docsy, now it's time to add some content! This page tells you how to use the theme to add and structure your site content.
 
 ## Content root directory
 
@@ -28,7 +28,7 @@ It also provides a [default "landing page" type of template](https://github.com/
 
 Each top-level **section** in your site corresponds to a **directory** in your site content root. Hugo automatically applies the appropriate **template** for that section, depending on which folder the content is in. For example, this page is in the `docs` subdirectory of the site's content root directory `content/en/`, so Hugo automatically applies the `docs` template. You can override this by explicitly specifying a template or content type for a particular page.
 
-If you've copied the example site, you already have appropriately named top-level section directories for using Docsy's templates, each with an index page ( `_index.md` or `index.html`) page for users to land on. These top-level sections also appear in the example site's [top-level menu](/docs/adding-content/navigation/#top-level-menu). 
+If you've copied the example site, you already have appropriately named top-level section directories for using Docsy's templates, each with an index page ( `_index.md` or `index.html`) page for users to land on. These top-level sections also appear in the example site's [top-level menu](/docs/adding-content/navigation/#top-level-menu).
 
 ### Custom sections
 
@@ -228,13 +228,14 @@ The minimum frontmatter you need to provide is a title: everything else is up to
 
 ## Page contents and markup
 
-By default you create pages in a Docsy site as simple [Markdown or HTML files](https://gohugo.io/content-management/formats/) with [page frontmatter](#page-frontmatter), as described above. Versions of Hugo before 0.60 use [BlackFriday](https://github.com/russross/blackfriday) as its Markdown parser. From 0.60, Hugo uses [Goldmark](https://github.com/yuin/goldmark/) as its Markdown parser by default.
+By default you create pages in a Docsy site as simple [Markdown or HTML files](https://gohugo.io/content-management/formats/) with [page frontmatter](#page-frontmatter), as described above.
+As of version 0.100, [Goldmark](https://github.com/yuin/goldmark/) is the only Markdown parser supported by Hugo.
 
 <div class="alert alert-primary" role="alert">
 
 <h4 class="alert-heading">Tip</h4>
 
-If you've been using earlier versions of Hugo, you may need to make some small changes to your site to work with the current Markdown parser. In particular, if you cloned an earlier version of our example site, add the following to your `config.toml`/`config.yaml`/`config.json` to allow Goldmark to render raw HTML as well as Markdown:
+If you've been using versions of Hugo before 0.60 that use [`BlackFriday`](https://github.com/russross/blackfriday) as its Markdown parser, you may need to make some small changes to your site to work with the current `Goldmark` Markdown parser. In particular, if you cloned an earlier version of our example site, add the following to your `config.toml`/`config.yaml`/`config.json` to allow Goldmark to render raw HTML as well as Markdown:
 
 {{< tabpane persistLang=false >}}
 {{< tab header="Configuration file:" disabled=true />}}
@@ -263,8 +264,6 @@ markup:
 {{< /tab >}}
 {{< /tabpane >}}
 
-Alternatively, if you want to continue using Blackfriday, you can follow the instructions in the [Hugo documentation](https://gohugo.io/getting-started/configuration-markup#blackfriday) to change the Markdown parser.
-
 </div>
 
 In addition to your marked-up text, you can also use Hugo and Docsy's [shortcodes](/docs/adding-content/shortcodes): reusable chunks of HTML that you can use to quickly build your pages. Find out more about shortcodes in [Docsy Shortcodes](/docs/adding-content/shortcodes).
@@ -289,7 +288,7 @@ We don't mandate any particular style for your page contents. However, if you'd
 
 ## Page bundles
 
-You can create site pages as standalone files in their section or subsection directory, or as folders where the content is in the folder's index page. Creating a folder for your page lets you [bundle](https://gohugo.io/content-management/page-bundles/) images and other resources together with the content. 
+You can create site pages as standalone files in their section or subsection directory, or as folders where the content is in the folder's index page. Creating a folder for your page lets you [bundle](https://gohugo.io/content-management/page-bundles/) images and other resources together with the content.
 
 You can see examples of both approaches in this and our example site. For example, the source for this page is just a standalone file `/content/en/docs/adding-content.md`. However the source for [Docsy Shortcodes](/docs/adding-content/shortcodes/) in this site lives in `/content/en/docs/adding-content/shortcodes/index.md`, with the image resource used by the page in the same `/shortcodes/` directory. In Hugo terminology, this is called a *leaf bundle* because it's a folder containing all the data for a single site page without any child pages (and uses `index.md` without an underscore).
 
@@ -303,13 +302,13 @@ The template you'll probably use most often is the [`docs` template](https://git
 * GitHub links (populated from your site config) for readers to edit the page or create issues
 * a page menu
 
-as well as the common header and footer used by all your site's pages. Which template is applied depends on whether you've added the content to the `blog` or `docs` content directory. You can find out more about how the nav and page menu are created in [Navigation and Search](/docs/adding-content/navigation/). 
+as well as the common header and footer used by all your site's pages. Which template is applied depends on whether you've added the content to the `blog` or `docs` content directory. You can find out more about how the nav and page menu are created in [Navigation and Search](/docs/adding-content/navigation/).
 
 ### Organizing your documentation
 
 While Docsy's top-level sections let you create site sections for different types of content, you may also want to organize your docs content within your `docs` section. For example, this site's `docs` section directory has multiple subdirectories for **Getting Started**, **Content and Customization**, and so on. Each subdirectory has an `_index.md` (it could also be an `_index.html`), which acts as a section index page and tells Hugo that the relevant directory is a subsection of your docs.
 
-Docsy's `docs` layout gives you a left nav pane with an autogenerated nested menu based on your `docs` file structure. Each standalone page or subsection `_index.md` or `_index.html`  page in the `docs/` directory gets a top level menu item, using the link name and `weight` metadata from the page or index. 
+Docsy's `docs` layout gives you a left nav pane with an autogenerated nested menu based on your `docs` file structure. Each standalone page or subsection `_index.md` or `_index.html`  page in the `docs/` directory gets a top level menu item, using the link name and `weight` metadata from the page or index.
 
 To add docs to a subsection, just add your page files to the relevant subdirectory. Any pages that you add to a subsection in addition to the subsection index page will appear in a submenu (look to the left to see one in action!), again ordered by page `weight`. Find out more about adding Docsy's navigation metadata in [Navigation and Search](/docs/adding-content/navigation/)
 
@@ -375,7 +374,7 @@ weight: 20
 
 ### Organizing your blog posts
 
-Docsy's `blog` layout also gives you a left nav menu (like the `docs` layout), and a list-type index page for your blog that's applied to `/blog/_index.md` and automatically displays snippets of all your recent posts in reverse chronological order. 
+Docsy's `blog` layout also gives you a left nav menu (like the `docs` layout), and a list-type index page for your blog that's applied to `/blog/_index.md` and automatically displays snippets of all your recent posts in reverse chronological order.
 
 To create different blog categories to organize your posts, create subfolders in `blog/`. For instance, in our [example site](https://github.com/google/docsy-example/tree/master/content/en/blog) we have `news` and `releases`. Each category needs to have its own `_index.md` or `_index.html` landing page file specifying the category title for it to appear properly in the left nav and top-level blog landing page. Here's the index page for `releases`:
 
@@ -469,7 +468,7 @@ Docsy's [default page template](https://github.com/google/docsy/blob/main/layout
 
 If you've copied the example site, you already have a simple site landing page in `content/en/_index.html`. This is made up of Docsy's provided Hugo shortcode [page blocks](/docs/adding-content/shortcodes/#shortcode-blocks).
 
-To customize the large landing image, which is in a [cover](/docs/adding-content/shortcodes/#blockscover) block, replace the `content/en/featured-background.jpg` file in your project with your own image (it can be called whatever you like as long as it has `background` in the file name). You can remove or add as many blocks as you like, as well as adding your own custom content. 
+To customize the large landing image, which is in a [cover](/docs/adding-content/shortcodes/#blockscover) block, replace the `content/en/featured-background.jpg` file in your project with your own image (it can be called whatever you like as long as it has `background` in the file name). You can remove or add as many blocks as you like, as well as adding your own custom content.
 
 The example site also has an About page in `content/en/about/_index.html` using the same Docsy template. Again, this is made up of [page blocks](/docs/adding-content/shortcodes/#shortcode-blocks), including another background image in `content/en/about/featured-background.jpg`. As with the site landing page, you can replace the image, remove or add blocks, or just add your own content.
 
@@ -602,7 +601,7 @@ If you're creating your own site and want to add a page using this template, add
 
 ## Adding static content
 
-You may want to serve some non-Hugo-built content along with your site: for example, if you have generated reference docs using Doxygen, Javadoc, or other doc generation tools. 
+You may want to serve some non-Hugo-built content along with your site: for example, if you have generated reference docs using Doxygen, Javadoc, or other doc generation tools.
 
 To add static content to be served "as-is", just add the content as a folder and/or files in your site's `static` directory. When your site is deployed, content in this directory is served at the site root path. So, for example, if you have added content at `/static/reference/cpp/`, users can access that content at `http://{server-url}/reference/cpp/` and you can link to pages in this directory from other pages at `/reference/cpp/{file name}`.
 
@@ -655,7 +654,7 @@ disableKinds:
 
 <h4 class="alert-heading">Note</h4>
 
-If you have enabled our [print feature](/docs/adding-content/print/) or otherwise specified section-level output formats in `config.toml`/`config.yaml`/`config.json`, make sure that `"RSS"` is listed as an output format, otherwise you won't get section-level RSS feeds (and your blog section won't get a nice orange RSS button). Your `config.toml`/`config.yaml`/`config.json` specification overrides the Hugo default [output formats](https://gohugo.io/templates/output-formats/) for sections, which are HTML and RSS.  
+If you have enabled our [print feature](/docs/adding-content/print/) or otherwise specified section-level output formats in `config.toml`/`config.yaml`/`config.json`, make sure that `"RSS"` is listed as an output format, otherwise you won't get section-level RSS feeds (and your blog section won't get a nice orange RSS button). Your `config.toml`/`config.yaml`/`config.json` specification overrides the Hugo default [output formats](https://gohugo.io/templates/output-formats/) for sections, which are HTML and RSS.
 
 {{< tabpane persistLang=false >}}
 {{< tab header="Configuration file:" disabled=true />}}

userguide/content/en/docs/Best practices/site-guidance.md

@@ -7,8 +7,8 @@ description: >
 ---
 
 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!
+If you're not already familiar with Hugo this page provides some useful tips and
+potential gotchas for adding and editing content for your site. Feel free to add your own!
 
 ## Linking
 
@@ -19,24 +19,3 @@ Note, however, that `ref` and `relref` links don't work with `_index` or `index`
 
 [Learn more about linking](/docs/adding-content/content/#working-with-links).
 
-## Nested lists (Blackfriday only)
-
-As of version 0.60.0, Hugo uses the [Goldmark](https://github.com/yuin/goldmark) Markdown processor.
-Prior to that version, [Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown processor.
-This processor 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),
-users still using Blackfriday as markup processor will achieve consistent behavior when using tabs for indentation. If you don't like tabs and want to use spaces for indentation, make sure you use 4 spaces for one indentation level, other you might run into trouble. Therefore, when using spaces for indentation,
-consider configuring your local editor to use 4 spaces when the **Tab** key is pressed.
-{{% /alert %}}