Cool Docs

• 1: Getting started
• 1.1: Test Page
• 2: Concepts
• 2.1: Understanding Webhooks
• 3: Topic guides
• 3.1: Add Algolia to your Hugo site
• 3.2: Upgrading Docsy
• 3.3: Mermaid Diagrams
• 4: Tutorials
• 4.1: Another Tutorial
• 5: Reference
• 5.1: Parameter Reference
• Cool Blog
• News About Docsy
• Easy documentation with Cool Docs
• 6.1.2: The second blog post
• 6.2: New Releases

1 - Getting started

Information in this section helps your user try your project themselves.

• What do your users need to do to start using your project? This could include downloading/installation instructions, including any prerequisites or system requirements.

• Introductory “Hello World” example, if appropriate. More complex tutorials should live in the Tutorials section.

Consider using the headings below for your getting started page. You can delete any that are not applicable to your project.

Prerequisites

Are there any system requirements for using your project? What languages are supported (if any)? Do users need to already have any software or tools installed?

Installation

Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them?

Setup

Is there any initial setup users need to do after installation to try your project?

Try it out!

Can your users test their installation, for example by running a command or deploying a Hello World example?

1.1 - Test Page

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

2 - Concepts

For many projects, users may not need much information beyond the information in the Overview, so this section is optional. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project (or to not make mistakes when using it) put that information in this section. For example, you may want to add some conceptual pages if you have a large project with many components and a complex architecture.

Remember to focus on what the user needs to know, not just what you think is interesting about your project! If they don’t need to understand your original design decisions to use or contribute to the project, don’t put them in, or include your design docs in your repo and link to them. Similarly, most users will probably need to know more about how features work when in use rather than how they are implemented. Consider a separate architecture page for more detailed implementation and system design information that potential project contributors can consult.

2.1 - Understanding Webhooks

What is a webhook?

Webhooks are user-defined HTTP callbacks triggered by specific events in a source application. Put more simply, they are automated messages sent between servers and apps when “something happens.”

You probably experience webhooks every day without realizing it, whether it’s Instagram adding you to the “browsed steak knives” list after you dwelled on a set of knives, or your bank texting you when your account balance drops below a certain threshold.

Webhooks play an important role in modern web applications and can be used for a variety of purposes that can help you improve your customer experience and streamline your business processes. This guide is a short introduction to webhooks with examples and resources for further exploration.

Core components of a webhook

Event

This is the trigger or the action that starts the process. An event can be any specific action or occurrence in the source application which initiates the webhook process, such as a database update, a server event, or a user action.

Payload

Once the event occurs, a payload, typically in JSON format, is created. This payload contains information about the event.

Webhook URL

This is the endpoint (URL) where the payload is sent. Each webhook URL is unique and typically linked to a specific action or response in the receiving application, e.g., https://api.example.com/webhooks/order-update. This endpoint is typically a RESTful API within the receiving application, designed to handle incoming webhook data.

Following is an example of an ecommerce event payload, which is sent as an HTTP POST request to the webhook URL, with the event type and timestamp included in the payload:

POST /webhooks/order-update HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "event": "order_created",
  "timestamp": "2023-11-14T12:30:45Z",
  "order": {
    "id": 123456,
    "status": "pending",
    "items": [
      {
        "product_id": 98765,
        "name": "Wireless Headphones",
        "quantity": 1,
        "price": 99.99
      },
      {
        "product_id": 12345,
        "name": "Bluetooth Speaker",
        "quantity": 2,
        "price": 49.99
      }
    ],
    "total_price": 199.97,
    "customer": {
      "customer_id": 7890,
      "name": "John Doe",
      "email": "johndoe@example.com",
      "shipping_address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345",
        "country": "USA"
      }
    }
  }
}

Webhook Receiver

The server that receives the webhook payload. It must be configured to accept POST requests and extract necessary information from the payload. The logic within the receiving application that processes the incoming webhook data. This often involves parsing the JSON payload, validating its authenticity, and executing business logic based on its contents.

Security

To ensure data integrity and security, webhooks often include signatures allowing the receiver to verify that the information is indeed from a trusted source such as cryptographic methods and HTTPS. This is especially important when the webhook payload contains sensitive information.

Acknowledgment & Error Handling

The receiver may send back HTTP response codes to acknowledge successful processing or indicate errors, which the source application can use for logging or retry logic.

Webhooks workflow diagram

Now that you have a basic understanding of the components of a webhook, let’s look at how they work together. The following diagram illustrates the typical workflow of a webhook:

1. Event Detection. The source application detects an event.
2. Trigger and Payload. The event triggers the webhook, which then sends a payload via an HTTP POST request to the webhook URL.
3. Webhook URL (Receiver). The webhook URL receives the payload.
4. Server Action The server at the receiver’s end processes this payload and can optionally send a response to the origination application or server.

sequenceDiagram
    participant U as User
    participant A as Source application
    participant W as Webhook URL (Receiver)
    participant S as Server action

    U->>A: Performs an action
    A->>A: Detects event
    Note right of A: Event triggers webhook
    A->>W: Sends payload via POST
    Note over W: Receives payload
    W->>S: Processes payload
    S->>W: Optional response
    Note over A,W: Communication via HTTPS

Advantages of Webhooks

• Real-Time Data Transfer: Webhooks provide real-time information transfer, which is faster than polling for updates.
• Efficiency: They reduce the need for continuous polling, saving resources and bandwidth.
• Customization and Flexibility: They can be configured for a wide variety of events and responses, making them highly adaptable to specific needs.

Common Implementations

Webhooks are a ubiquitous part of modern web applications and can be used for a variety of purposes. Some common use cases include:

• E-Commerce Notifications: Triggering inventory updates or order processing in response to a purchase transaction event.
• CI/CD Pipelines: Triggering build or deployment processes in response to source code repository events.
• Customer Support: Creating a support ticket when a user submits a form.
• Social Media: Sending notifications when a user posts a comment or shares a post.
• User profiling: Sending notifications when a user browses a product or service.
• Abandoned cart recovery: Sending reminders when a user abandons a cart.
• Service outages: Sending alerts when a service goes down or is unavailable.

Conclusion

Webhooks offer a powerful, efficient, and real-time way to integrate different systems and automate workflows. Organizations can leverage webhooks to streamline operations, enhance customer experience, and improve system interconnectivity.

Learn more

• Try out webhook.site to see how webhooks work in practice, test your own callbacks, and inspect webhook payloads. This is a great resource for experimenting with webhooks without having to set up your own server.
• If you’re not comfortable writing code, check out Zapier or IFTTT. These services allow you to create simple workflows using webhooks and other integrations, and can illustrate the power of webhooks in a few simple clicks.
• GitHub’s webhook documentation is a great place to start. It’s well-written, and provides a good overview of how webhooks work in practice.

3 - Topic guides

Think about your project’s features and use cases. Use these to choose your core tasks. Each granular use case (enable x, configure y) should have a corresponding tasks page or tasks page section. Users should be able to quickly refer to your core tasks when they need to find out how to do one specific thing, rather than having to look for the instructions in a bigger tutorial or example. Think of your tasks pages as a cookbook with different procedures your users can combine to create something more substantial.

You can give each task a page, or you can group related tasks together in a page, such as tasks related to a particular feature. As well as grouping related tasks in single pages, you can also group task pages in nested folders with an index page as an overview, as seen in this example site. Or if you have a small docset like the Docsy User Guide with no Tutorials or Concepts pages, consider adding your feature-specific pages at the top level of your docs rather than in a Tasks section.

Each task should give the user

• The prerequisites for this task, if any (this can be specified at the top of a multi-task page if they’re the same for all the page’s tasks. “All these tasks assume that you understand….and that you have already….”).
• What this task accomplishes.
• Instructions for the task. If it involves editing a file, running a command, or writing code, provide code-formatted example snippets to show the user what to do! If there are multiple steps, provide them as a numbered list.
• If appropriate, links to related concept, tutorial, or example pages.

3.1 - Add Algolia to your Hugo site

Overview

In this guide, you will learn how to add a customizable search experience to your Hugo site using open source tools from Algolia.

This guide will show you how to do the following:

1. Generate a search index using Hugo’s Custom output formats.
2. Send your search index to Algolia using the atomic-algolia npm package.
3. Display search results on your site using the free UI components available in the Algolia Autocomplete JavaScript libraries.

Prerequisites

Before you begin, you’ll need to have the following:

• A Hugo site
• An Algolia account and an application with the following details:
  • Application ID
  • Admin API key
  • Search-only API key

Generate your search index

In order to use Algolia, you must first create an index of your content in JSON or CSV format. In this tutorial we will create a JSON file using Hugo’s Custom output formats. After you have configured Hugo to generate the index, you’ll learn how to send this file to Algolia.

In your hugo.yml file, add the following to the outputs section:

# Algolia configuration

outputFormats:
  Algolia:
    baseName: algolia
    isPlainText: true
    mediaType: application/json
    notAlternative: true
params:
  algolia:
    vars:
      - title
      - summary
      - date
      - publishdate
      - expirydate
      - permalink
    params:
      - categories
      - tags

Now that you have added the Algolia output format, you can specify the structure of your search index using a JSON template.

Build your JSON template

In your site’s layouts directory, you will now build a Go template that generates the JSON file that you will send to Algolia. Depending on how your site is structured, you can edit the variables to expose attributes of your content that you want to index.

The following code is a good starting point for a basic Hugo documentation site. This template will do the following:

1. Create a JSON object for each page that is not a draft, and that does not have the hide or hideSearch parameters set to true.
2. Add the following attributes to each JSON object:
   • title
   • slug
   • keywords
   • path
   • date
   • weight
   • sectionWeight
   • section
   • layout
   • tags
   • categories
3. Add the sections attribute to each JSON object, which is an array of the page’s parent sections.
4. Add each JSON object to the index object, which is a map of the page’s permalink to the JSON object.

Add the following code to layouts/_default/algolia.json:

{{- /* Generates a valid Algolia search index */ -}}
{{- define "algolia-section-array" -}}
  {{- if and (not .parent.IsHome) .parent.Title -}}
    {{- if .parent.Parent -}}
      {{- template "algolia-section-array" (dict "scratch" .scratch "parent" .parent.Parent) -}}
    {{- end -}}
    {{- .scratch.Add "sections" .parent.Title -}}
  {{- end -}}
{{- end -}}

{{- $.Scratch.Set "index" dict -}}
{{- range .Site.RegularPages -}}
  {{- if and (not .Draft) (not .Params.hide) (not .Params.hideSearch) (not .IsHome) .IsPage -}}
    {{- $.Scratch.Set "record" dict -}}
    {{- if .Parent -}}
      {{- $.Scratch.Set "sections" slice -}}
      {{- template "algolia-section-array" (dict "scratch" $.Scratch "parent" .Parent) -}}
      {{- $.Scratch.SetInMap "record" "sections" ($.Scratch.Get "sections") -}}
    {{- end -}}
    {{- $.Scratch.SetInMap "record" "title" .Title -}}
    {{- $.Scratch.SetInMap "record" "slug" (path.Base .RelPermalink) -}}
    {{- $.Scratch.SetInMap "record" "keywords" .Keywords -}}
    {{- $.Scratch.SetInMap "record" "path" .RelPermalink -}}
    {{- $.Scratch.SetInMap "record" "date" .PublishDate -}}
    {{- $.Scratch.SetInMap "record" "weight" .Weight -}}
    {{- $.Scratch.SetInMap "record" "sectionWeight" (.Site.GetPage "section" .Section).Weight -}}
    {{- $.Scratch.SetInMap "record" "section" (.Site.GetPage "section" .Section).Title -}}
    {{- $.Scratch.SetInMap "record" "layout" .Layout -}}
    {{- $.Scratch.SetInMap "record" "tags" .Params.Tags -}}
    {{- $.Scratch.SetInMap "record" "categories" .Params.Categories -}}
    {{- $.Scratch.SetInMap "index" .RelPermalink ($.Scratch.Get "record") -}} 
  {{- end -}}
{{- end -}}
{{- $.Scratch.Get "index" | jsonify -}}

Now you are ready to generate your algolia.json search index.

Create a custom output format for Algolia

In hugo.yml, add the following:

outputs:
  home:
    - HTML
    - RSS
    - Algolia

By adding these output formats, when you build your production site with the hugo command, you will see a new algolia.json file in your public directory. You are ready to configure Algolia and send your search index to the service.

Configure Algolia

Head over to your Algolia dashboard and if you haven’t already, create a new application and an index.

Once you have created your application, retrive your app ID, index name and admin API key. Create an .env file in the root of your Hugo site and add the following variables:

ALGOLIA_APP_ID=<your_app_id>
ALGOLIA_ADMIN_KEY=<your_admin_key>
ALGOLIA_INDEX_NAME=<your_index_name>
ALGOLIA_INDEX_FILE=public/algolia.json

Replace the values with your own. If you have followed this guide so far, your algolia.json file will be in the public directory of your Hugo site. Change the path if you have a different setup.

Send your search index to Algolia

Now that you have your Algolia credentials, you can send your search index to Algolia. To do this, you will use the atomic-algolia npm package.

Install Atomic Algolia:

npm install atomic-algolia

Once installed and configured, Atomic Algolia will keep track of your search index and automatically update it when you make changes to your Hugo site. Atomic Algolia will only submit changes to your search index, so you don’t have to worry about sending the entire index every time you make a change, which can cut down on costs.

Once installed, add a new script to your package.json file:

{
  "scripts": {
    "algolia": "atomic-algolia"
  }
}

Now, you can run the following command at build/publish time to update your search index with changes to your content:

npm run algolia

Display search results on your site

Now that you have sent your search index to Algolia, the index is available to communicate with your front end and your users. To achieve this, use the Algolia Autocomplete JavaScript library.

Autocomplete is a great way to quickly enable a search experience using ready-made JavaScript components. To get a feel for how it works, try the search feature on this site, either by clicking into the search box in the top right corner, or by pressing the ⌘ K shortcut.

Install Autocomplete

Begin by installing the Autocomplete JavaScript library:

yarn add @algolia/autocomplete-js
# or
npm install @algolia/autocomplete-js

Add the Autocomplete CSS

Add the Autocomplete CSS to your project. You can either import it in your JavaScript file:

import '@algolia/autocomplete-theme-classic';

or add it in your HTML:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-theme-classic"
/>

Display search results

Now that you have installed the Autocomplete library, you can initialize the search client and display search results on your site. In this example, we will use a ready-made example from the Autocomplete documentation. Once you have it working, you can replace the example with your own App ID, index name and API key.

1. Create a container with an id #autocomplete where you want to display your search results.

<div id="autocomplete"></div>

2. Add this container to the relevant layout in your Hugo site, such as the layouts/_default/baseof.html file.

3. Create a new file in your Hugo site’s assets/js directory, or wherever you keep your compiled JavaScript files, and name it search.js, algolia.js or similar. Import it in your project:

import algoliasearch from 'algoliasearch/lite';
import { autocomplete, getAlgoliaResults } from '@algolia/autocomplete-js';

const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);

const autocompleteSearch = autocomplete({
  container: '#autocomplete',
  getSources() {
    return [
      {
        sourceId: 'querySuggestions',
        getItemInputValue: ({ item }) => item.query,
        getItems({ query }) {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: 'instant_search_demo_query_suggestions',
                query,
                params: {
                  hitsPerPage: 4,
                },
              },
            ],
          });
        },
        templates: {
          item({ item, components }) {
            return components.ReverseHighlight({ hit: item, attribute: 'query' });
          },
        },
      },
    ];
  },
});

Now that you have a working index of your site’s content in Algolia, and you have initialized the search client, you can display search results on your site.

Workflow diagram

This diagram shows the workflow for the steps in this guide.

3.2 - Upgrading Docsy

To upgrade Docsy, choose the latest version from the Releases section of the Docsy repo.

1. Update go.mod

module github.com/pfd/cool-docs

go 1.18

require github.com/google/docsy v0.7.1 // indirect

You can put your own repo, and go version, but it’s probably best to use the Docsy dependencies and Bootstrap version that is defined in the latest release.

2. Update dependencies

Update the latest dependencies, if necessary, in package.json.

  "devDependencies": {
    "autoprefixer": "^10.4.14",
    "postcss": "^8.4.24",
    "postcss-cli": "^10.1.0"
  }

3. Update config

If you’re updating the minimum Hugo version, reflect that in hugo.yml.

module:
  hugoVersion:
    extended: true
    min: 0.113.0
  imports:
    - path: github.com/google/docsy
      disable: false
    - path: github.com/google/docsy/dependencies
      disable: false

4. Run some commands

npm install

hugo mod tidy

5. Build your site!

hugo

If all goes well, your go.sum file should reflect the latest dependencies. Commit and push your changes to your repo.

3.3 - Mermaid Diagrams

graph TD
  Start --> Need{"Hugo version >= 0.93.0"}
  Need -- No --> Off["Set params.mermaid.enable = true"]
  Off --> Author
  Need -- Yes --> Author[Insert mermaid codeblock]

Mermaid Diagram

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
graph TD
    A[Start] --> B[Error Identification]
    B --> C[Check Logs]
    C -->|Found Logs| D[Analyze Logs]
    C -->|No Logs| E[Check System Status]
    D -->|Issue Found| I[Apply Fix Based on Logs]
    D -->|No Issue| E
    E -->|Resources OK| F[Check External Dependencies]
    E -->|Resource Issue| J[Resolve Resource Issues]
    F -->|Dependencies OK| G[User Error Check]
    F -->|Dependency Issue| K[Resolve Dependency Issues]
    G -->|User Error| L[Instruct User Correctly]
    G -->|No User Error| M[More Detailed Analysis]
    I --> N[End]
    J --> N
    K --> N
    L --> N
    M --> O[Escalate]
    O --> N
    click B href "https://www.github.com" "This is a link"

4 - Tutorials

Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. This section is optional. However, remember that although you may not need this section at first, having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.

4.1 - Another Tutorial

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5 - Reference

If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen, Javadoc, or other doc generation tools by putting them in your static/ directory. Find out more in Adding static content. For OpenAPI reference, Docsy also provides a Swagger UI layout and shortcode that renders Swagger UI using any OpenAPI YAML or JSON file as source.

5.1 - Parameter Reference

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Cool Blog

This is the blog section. It has two categories: News and Releases.

Files in these directories will be listed in reverse chronological order.

News About Docsy

Easy documentation with Cool Docs

This is a typical blog post that includes images.

The front matter specifies the date of the blog post, its title, a short description that will be displayed on the blog landing page, and its author.

Including images

Here’s an image (featured-sunset-get.png) that includes a byline and a caption.

The front matter of this post specifies properties to be assigned to all image resources:

resources:
- src: "**.{png,jpg}"
  title: "Image #:counter"
  params:
    byline: "Photo: Riona MacNamara / CC-BY-CA"

To include the image in a page, specify its details like this:

The image will be rendered at the size and byline specified in the front matter.

6.1.2 - The second blog post

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.

There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header

This is a normal paragraph following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Lorem markdownum tuta hospes stabat; idem saxum facit quaterque repetito occumbere, oves novem gestit haerebat frena; qui. Respicit recurvam erat: pignora hinc reppulit nos aut, aptos, ipsa.

Meae optatos passa est Epiros utiliter Talibus niveis, hoc lata, edidit. Dixi ad aestum.

Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Salt-n-Pepa
• Bel Biv DeVoe
• Kid ‘N Play

And an ordered list:

1. Michael Jackson
2. Michael Bolton
3. Michael Bublé

And an unordered task list:

• Create a sample markdown document
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Steal underpants
• ?
• Profit!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition terms are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

Components

Alerts

Sizing

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Parameters available

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Using pixels

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Using rem

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Memory

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

RAM to use

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

More is better

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Used RAM

Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This is the final element on the page and there should be no margin below this.

6.2 - New Releases