Writing content

Before you start writing

#

There are the following prerequisites before you start writing content:

• Decide how you want to contribute by choosing the contribution workflow and get a copy of the espressif / developer-portal repo
• To view the built version of the website, install Hugo in your environment and go through Getting started if required

Create and view an article

#

See also the official docs.

• To create a new article, determine the path and run

  hugo new content <path/index.md>
  # Example
  hugo new content blog/contribution-guide/index.md
  

  This assumes that you want to organize the content as a leaf bundle (the usual way). You can also use the branch bundle.
• To view the changes, in your project folder run

  hugo server
  

Add youself as an author

#

The default Espressif author is used:

• If the author prefers to stay anonymous
• For posts generated by scripts, such as automatic compilations, release notes, and so on
• For articles generated with AI

In other cases, add yourself as an author. For this, do the following:

• Create your author entry

  • At content/authors/<author-name>/_index.md, create your page
  • At data/authors/<author-name>.json, add your personal data

• Add the following to your article’s YAML header

  showAuthor: false         # Hide default Espressif author
  authors:
    - "<author-name>"        # List your name(s)
  

Write the content

#

This is totally up to you how you write the content as long as it is valuable for the community.

For writing and formatting conventions, the contributors at Espressif usually follow the Espressif Manual of Style and the Chicago Manual of Style. You might find these guidelines useful, but you are not required to follow them.

Prepare a featured image

#

A featured image appears above the article’s title. A nice and relevant image attracts readers like a magnet, that is why consider giving more thought to it.

A featured image can be added in the following ways from the highest to lowest priority:

• Article-specific image file: In the same folder as your article’s index.md, place your featured image and make sure its file name includes the substring feature, for example: featured-lcd-screen.webp.
• Image from a URL: In the article’s front matter, add the parameter featureimage and assign a URL to it, for example:

  featureimage: "https://espressif.com/logo-guidelines/chinese-horizontal-logo.png"
  

  This parameter is from Blowfish theme’s Front Matter.
• Generic image file: If you have no chance to create your own image, try to find a generic image in assets/img/featured and assign the path to featureAsset, for example:

  featureAsset: "img/featured/image.webp"
  

Use additional content types

#

Apart from the usual content types supported by markdown, such as visuals or code blocks, you can use other content types enabled by Hugo shortcodes. This section briefly introduces them.

If you need other types of content, either create a discussion on GitHub or offer a PR with the required functionality. It will be very much appreciated!

Images

#

Code blocks with tabs

#

Tabbed code blocks look neat:

Linux code block

macOS code block

At the same time, the markup is very simple:

{{< tabs groupId="config" >}}
  {{% tab name="Linux" %}}
```md
Linux code block
```
  {{% /tab %}}
  {{% tab name="macOS" %}}
Update homebrew, then run:
```md
macOS code block
```
  {{% /tab %}}
{{< /tabs >}}

Some explanations:

• Use the tabs shortcode to create a tabbed code block
• Use the nested tab shortcode to create as many tabs as you need
• Within a tab, place any markdown content you want, it will be rendered like any other markdown content

For a real example, see this page.

As you can see, the tabs shortcode has the parameter groupId. It creates association between all tabbed code blocks bearing the same groupId on a webpage. Once you choose a certain tab, all associated code blocks will switch to the same tab. It can be useful in tutorials covering multiple operating systems, programming lanugages, etc.

You can also easily indent a tabbed code block, by preceding the tabs and tab shortcodes with the required number of spaces. This is exactly what was done in the linked example above.

Diagrams as code

#

A number of Diagrams as code formats are supported, including Mermaid.

For example, a Mermaid diagram is used on this page (see also the raw version).

Asciinema casts

#

asciinema casts

Video

#

Youtube videos using Hugo shortcodes

Ask for review

#

To publish your content on the Espressif Developer Portal, please create a discussion in espressif / developer-portal invite reviewers from Espressif so that they can make sure your content is in-line with Espressif’s writing conventions.

After the review is done, create a PR following the contribution workflow.