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

Now to create a new article, run in the root of your cloned developer portal git repo:

# 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

The commands above assume that you want to write a single article (leaf bundle). The recommended article folder structure is as follows:

📂 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

For multi-article entries, such as workshops, etc., use the branch bundle.

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 youself as an author

#

To add yourself as an author, 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, it might be better to add 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 the article

#

To preview the article:

• Run in your project folder:

  hugo server
  

• 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