Content writing workflow

Before you start writing

#

There are the following prerequisites before you start writing content:

• Decide how you want to contribute by choosing the content 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.

Use additional content types

#

Apart from the usual content types supported by markdown, such as visuals or code snippets, you can also include:

• Diagrams as code
  • Mermaid diagrams are supported, for an example see the raw version of this page
• Youtube videos using Hugo shortcodes
• asciinema casts

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!

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 content contribution workflow.