Skip to content

Latest commit

 

History

History
245 lines (163 loc) · 9.25 KB

index.md

File metadata and controls

245 lines (163 loc) · 9.25 KB
Raw
title date tags showTableOfContents showAuthor authors
Writing content
2024-04-29 14:25:01 +0800
Contribute
true
false
kirill-chalov

Before you start writing

There are the following prerequisites before you start writing content:

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"

Please have your featured image converted to WebP as requested in Use WebP for raster images.

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 the most relevant shortcodes implemented on the Espressif Developer Portal.

In addition to that, you can also use the standard Hugo embedded shortcodes and Blowfish theme shortcodes.

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

Images

Adding images

You can add an image using a standard markdown syntax:

![Alt text](path/to/image.webp "Optional tooltip")

However, the Blowfish theme used on this website provides the figure shortcode that offers more control over image display and render. An example of a shortcode is given below, but more parameters are available:

{{</* figure
    src="image.webp"
    alt=""
    caption=""
    */>}}

By default, the Blowfish theme optimizes the images for different device resolutions. For some images, the processing adds grey background. To fix it, disable the processing of such images by adding the parameter default="false" to the figure shortcode.

Use WebP for raster images

For raster images, please use the WebP format only. The Developer Portal's CI blocks the images in PNG anf JPEG format.

The WebP format was chosen for the following reasons:

  • The images in WebP are comparable in quality to PNG and JPEG but are 5-7 times smaller in size
  • Smaller image size is important
    • It prevents the git repo from growing out of proportion very fast
    • It allows serving web pages faster

To convert your images to WebP, use one of the following ways:

  • Use imagemagick:

    convert image.jpg -quality 60 image.webp

  • Use cwebp:

    cwebp -q 60 image.jpg -o image.webp

The quality value 60 usually yields good results. For very good quality, you can use the value 80.

Asciinema casts

Asciinema allows you to record terminal sessions using a lightweight text-based format.

If you want to use an asciinema cast in your article, see asciinema casts.

Code blocks with tabs

Tabbed code blocks look neat:

{{< tabs groupId="config" >}} {{% tab name="Linux" %}}

Linux code block

{{% /tab %}} {{% tab name="macOS" %}} Update homebrew, then run:

macOS code block

{{% /tab %}} {{< /tabs >}}

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

Video

To embed a YouTube video in your article, use the Hugo shortcode.

Use pre-commit

This project has a pre-commit hook that can perform the following checks:

  • Enforce coding standards and best practices in the project's codebase
  • Check links using lychee
    • Important: this check requires Docker as a dependency, please make sure it is installed

If you want to use pre-commit, in your project folder, run:

# Install requirements
pip install -r requirements.txt
# Set up git hook scripts
pre-commit install
# Remove git hook scripts (if not needed)
pre-commit uninstall

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.