Skip to main content

Tags

Blog tags are configured in blog/tags.yml. Every tag has a label, a URL, and a description.

File Location​

blog/tags.yml

Basic Structure​

docusaurus:
  label: Docusaurus
  permalink: /docusaurus
  description: Docusaurus documentation system tutorials and guides.

Fields​

FieldRequiredPurpose
labelYesTag display name
permalinkYesURL path for the tag page
descriptionNoTag description

Adding a Tag​

Add a new entry to tags.yml:

your-tag:
  label: Your Tag
  permalink: /your-tag
  description: A short description of your tag.

The key (your-tag) is what you reference in blog posts.

Using Tags in Blog Posts​

Add tags to the frontmatter:

---
title: "My Post"
tags:
  - docusaurus
  - comparison
---

Multiple tags are supported. The post appears under all of them.

Tag Pages​

Every tag gets its own page at:

/blog/tags/your-tag

The page lists all posts with that tag.

Default Tags​

Nocturne ships with 13 tags:

KeyLabel
docusaurusDocusaurus
documentationDocumentation
decapDecap CMS
jamstackJAMstack
searchSearch
designDesign
tutorialTutorial
deploymentDeployment
comparisonComparison
axcoraAxcora
migrationMigration
freeFree
performancePerformance

The permalink field defines the tag page URL:

PermalinkURL
/docusaurus/blog/tags/docusaurus
/search/blog/tags/search
/comparison/blog/tags/comparison

Keep permalinks short — no /blog/tags/ prefix needed.

Description​

Tag descriptions appear on the tag page and in SEO metadata.

Example:

docusaurus:
  label: Docusaurus
  permalink: /docusaurus
  description: Docusaurus documentation system tutorials and guides.

Keep descriptions to one sentence.

Best Practices​

  • Use 3–6 tags per post — enough for discovery, not too many
  • Keep tags lowercase — docusaurus, not Docusaurus
  • Use consistent tags — repeat across posts
  • Write clear descriptions — helps SEO
  • Don't create too many tags — 10–15 is a good range

Tag Strategy​

Good tags describe topics, not formats:

GoodBad
docusaurusdocusaurus-tutorial
documentationhow-to-write-docs
decapdecap-cms-guide
designdesign-tips

Topic-based tags scale better. Format-based tags multiply.

Troubleshooting​

Tag doesn't show on the post​

  1. Check that the tag exists in tags.yml
  2. Check the spelling in the frontmatter
  3. Restart the dev server

Tag page returns 404​

Check that the tag is defined in tags.yml. Tags not defined there don't get pages.

Tag pages show wrong posts​

  1. Check that the tag is spelled the same in all posts
  2. Check for case differences — docusaurus vs Docusaurus

Too many tags​

Consolidate. Merge similar tags into one:

BeforeAfter
docusaurus-tutorial + docusaurus-guidedocusaurus
decap-cms + decap-setupdecap