Changelog System for Your Digital Garden

Overview

The changelog system allows you to document all changes made to your notes over time. Each note can have an associated changelog that tracks what was added, revised, or deleted.

Structure

1. Note Front Matter

Add a changelog_url field to your note’s front matter to link it to a changelog:

---
title: Your Note Title
status: wip
topics:
    - your-topic
changelog_url: /changelogs/your-note-slug/
---

The changelog_url should point to where your changelog page will be published.

2. Changelog File Location

Create changelog files in the _changelogs/ directory:

_changelogs/
  ├── your-first-note.md
  ├── example-note.md
  └── another-note.md

3. Changelog Front Matter

Each changelog file should have the following front matter:

---
layout: changelog
title: Changelog - Your Note Title
note_title: Your Note Title
note_url: /your-note-slug/
permalink: /changelogs/your-note-slug/
---

• layout: Always use changelog
• title: The title of the changelog page
• note_title: The title of the associated note
• note_url: The URL to the associated note
• permalink: The URL where the changelog will be published

4. Changelog Entry Structure

Changelog entries are created using the changelog_entry include component. Each entry can contain multiple actions:

<div class="changelog-entry" style="margin: 2em 0; padding: 1.5em; background: #f9f9f9; border-left: 4px solid #8b88e6; border-radius: 4px;">
  <h3 style="margin-top: 0;">Entry Title</h3>
  
  <p style="color: #666; font-size: 0.9em; margin: 0.5em 0;">
    
      Created: November 15, 2025
    
    
      | Updated: November 20, 2025
    
  </p>

  
    <div style="margin-top: 1em;">
      
        <div style="margin: 0.8em 0; padding: 0.8em; background: white; border-radius: 3px;">
          <strong style="color: #8b88e6;">:</strong> 
        </div>
      
    </div>
  
</div>

Parameters:

• title (string): The title of this changelog entry
• date_published (date): When this change was first published (YYYY-MM-DD format)
• date_updated (date): When this change was last updated (YYYY-MM-DD format)
• actions (JSON array): Array of action objects

Action Types:

• Added: Use when new content or features are introduced
• Revised: Use when existing content is modified or improved
• Deleted: Use when content or features are removed

5. Example Changelog Entry

<div class="changelog-entry" style="margin: 2em 0; padding: 1.5em; background: #f9f9f9; border-left: 4px solid #8b88e6; border-radius: 4px;">
  <h3 style="margin-top: 0;">Initial Publication</h3>
  
  <p style="color: #666; font-size: 0.9em; margin: 0.5em 0;">
    
      Created: November 10, 2025
    
    
      | Updated: November 10, 2025
    
  </p>

  
    <div style="margin-top: 1em;">
      
        <div style="margin: 0.8em 0; padding: 0.8em; background: white; border-radius: 3px;">
          <strong style="color: #8b88e6;">:</strong> 
        </div>
      
    </div>
  
</div>


<div class="changelog-entry" style="margin: 2em 0; padding: 1.5em; background: #f9f9f9; border-left: 4px solid #8b88e6; border-radius: 4px;">
  <h3 style="margin-top: 0;">Expanded Examples</h3>
  
  <p style="color: #666; font-size: 0.9em; margin: 0.5em 0;">
    
      Created: November 10, 2025
    
    
      | Updated: November 25, 2025
    
  </p>

  
    <div style="margin-top: 1em;">
      
        <div style="margin: 0.8em 0; padding: 0.8em; background: white; border-radius: 3px;">
          <strong style="color: #8b88e6;">:</strong> 
        </div>
      
    </div>
  
</div>


<div class="changelog-entry" style="margin: 2em 0; padding: 1.5em; background: #f9f9f9; border-left: 4px solid #8b88e6; border-radius: 4px;">
  <h3 style="margin-top: 0;">Fixed Typos</h3>
  
  <p style="color: #666; font-size: 0.9em; margin: 0.5em 0;">
    
      Created: November 10, 2025
    
    
      | Updated: December 2, 2025
    
  </p>

  
    <div style="margin-top: 1em;">
      
        <div style="margin: 0.8em 0; padding: 0.8em; background: white; border-radius: 3px;">
          <strong style="color: #8b88e6;">:</strong> 
        </div>
      
    </div>
  
</div>

How It Works

1. On the Note: The note displays “Created on {Date}

   Updated on {Date}

   Changelog” in the header

2. Clicking the Changelog Link: Takes you to the note’s changelog page
3. On the Changelog: Shows all entries documenting changes to the note over time
4. Back Link: A “Back to note” link on the changelog allows easy navigation back

Visual Design

• Changelog entries have a light gray background with a purple left border
• Each action is displayed in its own box with the action type highlighted in purple
• Dates are formatted as “Month Day, Year” for consistency
• The layout is responsive and follows your garden’s design system

Tips

1. Keep Entries Organized: Group related changes in a single entry
2. Use Clear Descriptions: Make it easy for readers to understand what changed
3. Consistent Dates: Use ISO format (YYYY-MM-DD) for dates to ensure proper parsing
4. Link to Notes: The changelog automatically links back to the note
5. Multiple Actions: You can have as many actions as needed in one entry

Files Modified/Created

• _layouts/changelog.html - Layout for changelog pages
• _includes/changelog_entry.html - Component for individual changelog entries
• _changelogs/ - Directory for changelog files
• _layouts/note.html - Updated to include changelog link

This line appears after every note.