Skip to main content

Content Fields Reference Card

Quick reference for all content fields in your CMS.

✅ REQUIRED FIELDS (Must Have)​

FieldTypeMax LengthDescriptionExample
titleString~60 charsMain article title"Building Your First AI Agent"
slugString-URL-friendly version"building-your-first-ai-agent"
content_typeEnum-Type of content"blog" | "tutorial" | "lesson" | "tip" | "case_study"
access_levelEnum-Who can view"public" | "registered" | "premium" | "course_specific"
contentJSON-Main content body (Tiptap JSON)See structure below

Conditional Required:

  • track_id: Required ONLY when access_level = "course_specific"

📝 OPTIONAL FIELDS (Recommended)​

FieldTypeMax LengthDescriptionExample
subtitleString~100 charsTagline/subtitle"A beginner's guide to AI automation"
excerptString150-200 charsPreview description"Learn how to build your first AI agent in just 30 minutes..."
category_idUUID-Content categoryUUID or null
tagsArray-Searchable tags["ai", "automation", "tutorial"]
difficulty_levelEnum-Content difficulty"beginner" | "intermediate" | "advanced"
featured_imageString-Image URL"https://example.com/image.jpg"
video_urlString-YouTube/Vimeo URL"https://youtube.com/watch?v=..."
meta_titleString60 charsSEO title"Build AI Agents - Complete Guide 2025"
meta_descriptionString160 charsSEO description"Learn to build AI agents from scratch..."

🔐 ACCESS LEVELS Explained​

LevelWho Can ViewUse Case
publicEveryone (no login)Marketing content, free resources
registeredLogged-in users onlyIncentivize signups
premiumPaid subscribersPremium content, courses
course_specificEnrolled in specific courseCourse lessons, materials

📂 AVAILABLE CATEGORIES​

  • AI Agents - Building and deploying AI agents
  • Automation - Process automation and workflows
  • Tutorials - Step-by-step guides
  • Case Studies - Real-world examples
  • Best Practices - Industry standards
  • News & Updates - Latest developments

📊 CONTENT TYPES Explained​

TypeDescriptionTypical LengthStructure
blogThought leadership, insights1200-1500 wordsIntro → 3-4 sections → Conclusion
tutorialStep-by-step how-to1500-2500 wordsPrerequisites → Steps → Troubleshooting
lessonEducational content1000-1500 wordsLearning objectives → Content → Quiz/Exercise
tipQuick actionable advice500-800 wordsProblem → Solution → Example
case_studyReal-world application1500-2000 wordsChallenge → Solution → Results

🎯 DIFFICULTY LEVELS​

LevelAssumesTypical Topics
beginnerNo prior knowledge"What is an AI Agent?", "Getting Started"
intermediateBasic understanding"Building a chatbot", "Using LangChain"
advancedExpert knowledge"Scaling in production", "Custom architectures"

📋 TIPTAP CONTENT STRUCTURE​

Your content must be in Tiptap JSON format:

Basic Structure​

{
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 2 }, "content": [...] },
    { "type": "paragraph", "content": [...] },
    { "type": "bulletList", "content": [...] }
  ]
}

Available Node Types​

Node TypeAttributesUse For
headinglevel: 1-6Section titles (use 2-3)
paragraph-Normal text
bulletList-Unordered lists
orderedList-Numbered lists
listItem-Individual list items
codeBlocklanguageCode examples
blockquote-Quotes
hardBreak-Line break
horizontalRule-Divider

Available Text Marks​

MarkAttributesExample
bold-Bold text
italic-Italic text
code-inline code
linkhref, targetLink
strike-Strikethrough

Example: Complete Content​

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [
        { "type": "text", "text": "Introduction" }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This is " },
        {
          "type": "text",
          "marks": [{ "type": "bold" }],
          "text": "bold text"
        },
        { "type": "text", "text": " and this is " },
        {
          "type": "text",
          "marks": [{ "type": "italic" }],
          "text": "italic"
        },
        { "type": "text", "text": "." }
      ]
    },
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [
        { "type": "text", "text": "Main Points" }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                { "type": "text", "text": "First point" }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                { "type": "text", "text": "Second point" }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": { "level": 3 },
      "content": [
        { "type": "text", "text": "Code Example" }
      ]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "python" },
      "content": [
        {
          "type": "text",
          "text": "def hello_world():\n    print('Hello, World!')"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Learn more at " },
        {
          "type": "text",
          "marks": [
            {
              "type": "link",
              "attrs": {
                "href": "https://example.com",
                "target": "_blank"
              }
            }
          ],
          "text": "our website"
        },
        { "type": "text", "text": "." }
      ]
    }
  ]
}

🏷️ TAG RECOMMENDATIONS​

Best Practices for Tags​

  • Use 5-7 tags per article
  • Mix broad and specific tags
  • Use lowercase
  • Use hyphens for multi-word tags
  • Be consistent across articles

Common Tags by Category​

AI Agents:

  • ai-agents
  • langchain
  • openai
  • chatbots
  • autonomous-agents

Automation:

  • automation
  • workflow
  • rpa
  • zapier
  • make

Technical:

  • python
  • javascript
  • api
  • tutorial
  • code

Business:

  • case-study
  • roi
  • productivity
  • business
  • strategy

Level:

  • beginner
  • intermediate
  • advanced
  • getting-started

📸 FEATURED IMAGE Guidelines​

  • Minimum: 1200x630px (Open Graph standard)
  • Ideal: 1920x1080px
  • Aspect Ratio: 16:9 or 2:1
  • Format: JPG or PNG
  • File Size: < 500KB

Image Sources​

  • Unsplash (free, high-quality)
  • Pexels (free)
  • Custom screenshots
  • Diagrams/infographics

Alt Text​

Always describe the image for accessibility and SEO.

🎬 VIDEO URLs​

Supported Platforms​

  • YouTube: https://youtube.com/watch?v=VIDEO_ID
  • Vimeo: https://vimeo.com/VIDEO_ID

Video Types​

  • Tutorial walkthroughs
  • Product demos
  • Case study interviews
  • Supplementary content

📈 SEO OPTIMIZATION​

Meta Title (60 chars max)​

  • Include primary keyword
  • Front-load important words
  • Make it compelling
  • Example: "Build AI Agents: Complete Python Guide 2025"

Meta Description (160 chars max)​

  • Expand on title
  • Include call-to-action
  • Use keywords naturally
  • Example: "Learn to build AI agents from scratch with Python, LangChain, and OpenAI. Step-by-step tutorial for developers. Start now!"

Keywords to Include​

  • Primary keyword in title
  • Primary keyword in first paragraph
  • Secondary keywords in H2 headings
  • LSI keywords throughout content
  • Keywords in meta description

✏️ CONTENT WRITING TIPS​

Structure​

  1. Hook (first 2-3 sentences)
  2. Problem Statement
  3. Solution Overview
  4. Detailed Content (3-5 sections)
  5. Summary/Key Takeaways
  6. Call-to-Action

Writing Style​

  • Active voice: "You can build" not "Can be built"
  • Second person: "You will learn" not "Readers will learn"
  • Short paragraphs: 2-4 sentences max
  • Subheadings: Every 200-300 words
  • Examples: Real-world, practical
  • Transitions: Connect ideas smoothly

Readability​

  • Flesch Reading Ease: > 60
  • Sentence length: < 20 words average
  • Paragraph length: < 150 words
  • Use bullet points for lists
  • Use visuals to break up text

🔍 VALIDATION CHECKLIST​

Before saving content, verify:

  • Title is compelling and < 60 chars
  • Slug is URL-friendly (lowercase, hyphens)
  • Content type is selected
  • Access level is appropriate
  • Content body is not empty
  • Content is properly formatted (Tiptap JSON)
  • Excerpt is 150-200 characters
  • 5-7 relevant tags added
  • Category is selected
  • Difficulty level matches content
  • Meta title < 60 chars with keywords
  • Meta description < 160 chars
  • Featured image URL is valid
  • All links work (if any)
  • Code examples are tested (if any)
  • Grammar and spelling checked

💾 FIELD SANITIZATION​

The system automatically handles:

  • Empty category → null ✅
  • Empty track → null ✅
  • Empty optional fields → null ✅
  • Empty tags → [] ✅

You can safely leave optional fields empty!

🚨 COMMON ERRORS​

ErrorCauseFix
"Title is required"Empty title fieldEnter a title
"Slug is required"Empty slugEnter slug or it auto-generates from title
"Content body is required"Empty editorAdd content to editor
"Course/Track is required"access_level = course_specific but no trackSelect a course or change access level
"invalid UUID"Should not happen anymore!System auto-converts empty to null

📚 QUICK REFERENCE​

Minimum Required to Publish:

  1. Title ✅
  2. Slug ✅ (auto-generated)
  3. Content Type ✅
  4. Access Level ✅
  5. Content Body ✅

Recommended to Add:

  • Excerpt (for better previews)
  • Tags (for discoverability)
  • Category (for organization)
  • Meta fields (for SEO)
  • Featured image (for visual appeal)

Optional but Valuable:

  • Subtitle
  • Video
  • Difficulty level

Last Updated: 2025-11-01 Version: 1.0