Skip to main content
This workflow covers the editorial process for creating and publishing notes content in the Dex system.

​
Overview

The notes editorial workflow provides:
  • Streamlined note creation and editing
  • Frontmatter validation and build checks
  • Safe publication to production
  • Integration with the Dex Notes system

​
Workflow Steps

1

Edit the note

Open the target note in your configured editor:
dex notes edit --slug <slug>
This opens the note’s markdown file in $EDITOR.Note structure:
  • Frontmatter: YAML metadata (title, date, status, etc.)
  • Content: Markdown body
Make your editorial changes and save the file.
Ensure frontmatter is valid YAML. Invalid frontmatter will cause build failures.
2

Validate the notes

Run validation to check all notes for errors:
dex notes validate
Validation checks:
  • Frontmatter schema compliance
  • Required field presence
  • Date format validity
  • Slug uniqueness
  • Markdown syntax
Fix any validation errors before proceeding.
3

Publish the notes bundle

After successful validation, publish the notes:
dex notes publish
This command:
  1. Runs dex notes build to generate static files
  2. Validates the built output
  3. Publishes to production

​
Creating New Notes

To create a new note draft: 
# Create with auto-generated slug
dex notes add

# Create with specific title and slug
dex notes add --title "My New Post" --slug my-new-post
This creates a new markdown file with scaffolded frontmatter that you can edit.

​
Managing Note Metadata

Update frontmatter fields without opening the editor: 
# Set a single field
dex notes set --slug <slug> --field status --value published

# Set JSON field
dex notes set --slug <slug> --field tags --value '["editorial","featured"]' --json

# Update title
dex notes set --slug <slug> --field title --value "Updated Title"

​
Building Notes Locally

Test the build process without publishing: 
# Build all notes
dex notes build

# Validate build output
dex notes validate
Built files are generated in the configured output directory for local review.

​
TUI Notes Manager

Launch the interactive notes manager from the dashboard: 
dex
# Select "Notes" from dashboard
Available actions:
  • a - Add new post draft
  • e - Edit selected post in $EDITOR
  • t - Set title for selected post
  • b - Build notes bundle
  • v - Validate notes
  • r - Reload notes list
  • Up/Down - Navigate posts
  • Esc - Return to dashboard

​
Verification Commands

# List all notes with status
dex notes list

# Validate notes structure and frontmatter
dex notes validate

# Build notes locally for review
dex notes build

​
Stop Conditions

Do not publish if:
  • dex notes validate reports any errors
  • Frontmatter is malformed or missing required fields
  • Build process fails or produces warnings
  • Content contains placeholder or incomplete sections

​
Next Steps

After publishing notes:

Entry Validation

Create and validate new catalog entries

Release Process

Coordinate full release with other content

​
Troubleshooting

​
Frontmatter validation errors

Symptom: dex notes validate reports YAML parsing errors or missing required fields. Fix:
  1. Open the failing note: 
    dex notes edit --slug <slug>
  2. Check frontmatter syntax:
    • Ensure proper YAML formatting
    • Verify all required fields are present (title, date, status)
    • Check for unescaped special characters in strings
  3. Re-run validation: 
    dex notes validate

​
Build failures

Symptom: dex notes build exits with errors. Fix:
  1. Review build error messages for specific file/line references
  2. Common issues:
    • Invalid markdown syntax
    • Broken internal links
    • Missing or malformed frontmatter
  3. Fix issues and rebuild: 
    dex notes build

​
Editor not configured

Symptom: dex notes edit fails with “no editor configured” error. Fix:
  1. Set $EDITOR environment variable: 
    export EDITOR=vim  # or nano, emacs, code, etc.
  2. Add to shell profile (.bashrc, .zshrc) for persistence: 
    echo 'export EDITOR=vim' >> ~/.bashrc
  3. Retry edit command

Build docs developers (and LLMs) love

Get started for freeTalk to us