Create article scaffold

Create an article

#

Please start by checking out file and folder naming conventions:

• In file and folder names, use kebab-case (and no underscores).
  Example: my-article-title
• For article folder name use a short form of the article title including all key words.
  Example: esp-idf-tutorial-gpio-get-started
• Place your blog article under content/blog/YYYY/MM/ matching its publication date.
  Example: content/blog/2026/02/esp-idf-tutorial-gpio-get-started/index.md

The recommended article folder structure is given below. For multi-article entries, such as workshops, etc., use the branch bundle.

📂 content/blog/YYYY/MM/
└── 📂 <article-folder-name>/
    ├── 📝 index.md       # article content
    ├── 📊 featured.webp  # article feature image (banner)
    ├── 📂 img/
    │   ├── 📊 image1.webp
    │   └── 📊 image2.webp
    └── 📂 asciinema/
        ├── 💻 asciinema1.cast
        └── 💻 asciinema2.cast

Now with the naming conventions and folder structure covered, you can create a new article scaffold.

• If you don’t have Hugo installed, create the folders and files manually
• (recommended) With Hugo installed (see gohugo.io or GitHub releases), create the article scaffold automatically, go to the root of your developer portal repo and run:

  # Blog article
  # (if specified folders don't exist, they will be created)
  hugo new content blog/YYYY/MM/<article-folder-name>/index.md
  # Blog article example
  hugo new content blog/2026/02/esp-idf-tutorial-gpio-get-started/index.md
  # Non-blog articles (workshops, events etc.)
  hugo new content <path>/index.md

Fill out the blog article front matter

#

After creating a blog article using hugo new content blog/..., go to your article file index.md and fill out its YAML front matter according to the instructions in comments.

One of the YAML parameters is summary — the article summary that appears just below the article title (summary example) and also in the article card (card example) where articles are listed. You can leave summary empty for now. We will discuss how to write the article summary in Write and format content.

Add yourself as an author

#

If it is your first contribution, please add yourself as an author. For this, create an article and run the script in the repo root:

python3 tools/create_author.py

This script partially automates the following instructions:

• Create your author entry
  
  Replace all author-name and Author Name instances below with your own name, for example john-doe and John Doe respectively
  • Create your page at content/authors/author-name/_index.md

    ---
    title: Author Name
    ---
    
    <!-- (optional) Add a few words about yourself  -->

  • (optional) Add your image in WebP format at the path

    assets/img/authors/author-name.webp

  • Add your personal data at data/authors/author-name.json
    
    • image – add your image or use the default img/authors/espressif.webp
    • type – set author type to espressif, partner, or community

    {
        "name": "Author Name",
        "type": "espressif",
        "image" : "img/authors/author-name.webp",
        "bio": "(optional) Your role at Espressif",
        "social": [
            { "linkedin": "https://www.linkedin.com/..." },
            { "github": "https://github.com/..." }
        ]
    }

• Add author name(s) to your article’s YAML header

  authors:
    - "author-name" # same as in the file paths above
    - "another-author"

In some cases, the content coming from Espressif might be better to mark with the default Espressif author:

• 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

To add the default author, include this in your article’s YAML header:

showAuthor: true

Preview in HTML

#

Make sure your local environment is ready:

• Install a Hugo version listed in the README badges
  • If your branch is well behind main, install a Hugo version listed in themes/blowfish/config.toml
• In your local project’s folder, update the submodules using git submodule update --init --recursive

Preview the article:

• Run in your project folder:

  hugo server

  • If you have issues, make sure you use up-to-date syntax in your content
• In the log, find the preview web address and open it:

  Web Server is available at http://localhost:1313/

• Navigate to your article: In the website header, click Blog and find your article card

Next step

#

Next article → Write and format content

Back to the Contribution guide