index.md

title	date	tags	showAuthor	authors
Content writing workflow	2024-04-29 14:25:01 +0800	Contribute	false	kirill-chalov

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.

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