Smart Markdown: Dynamic Variable Substitution for Living Documents

A Technical Note on Implementing Transclusion in Content Management Systems

Document ID: CNL-TN-2025-006
Version: 1.0
Date: December 5, 2025
Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This technical note was developed with assistance from Claude (Anthropic). The AI contributed to historical research, code patterns, and documentation drafting. The author takes full responsibility for the content, accuracy, and conclusions.

Abstract

This technical note describes Smart Markdown, a lightweight implementation of dynamic variable substitution for markdown-based content management systems. The system allows authors to embed tokens (e.g., {{essay_count}}) within document content that resolve to current database values at render time, creating "living documents" that remain accurate without manual updates. The approach draws inspiration from Ted Nelson's concept of transclusion—the inclusion of content by reference rather than by copy—and represents a practical implementation of ideas first articulated in the early hypertext literature. This document provides theoretical grounding, implementation specifications, and integration patterns for the Coffee with Claude (CWC) blog infrastructure.

1. Introduction

1.1 The Problem of Static Content

Traditional content management systems store documents as static text. When an author writes "this blog contains twenty-eight essays," that number becomes frozen at the moment of writing. As the corpus grows, the statement becomes false, requiring manual correction—a task easily forgotten and rarely prioritized.

This problem is endemic to digital publishing. Introductory pages, "about" sections, statistical summaries, and cross-references all suffer from temporal decay. The document says one thing; reality has moved on.

1.2 The Transclusion Solution

The solution is conceptually simple: rather than embedding static values, embed references that resolve dynamically. The document stores {{essay_count}} rather than "twenty-eight." At render time, the system queries the database and substitutes the current value. The document stays true.

This approach—content inclusion by reference rather than by copy—was articulated by Ted Nelson in the 1960s under the term "transclusion." While Nelson's full vision encompassed bidirectional links, version management, and micropayment systems, the core insight remains applicable: documents should reference authoritative sources rather than duplicate information that will inevitably drift from accuracy.

1.3 Scope

This technical note covers:

• Historical and theoretical foundations
• Smart Markdown syntax specification
• Implementation architecture for LAMP-based CMS
• Integration with the CWC blog infrastructure
• Extension patterns for future development

2. Historical Foundations

2.1 Vannevar Bush and the Memex (1945)

The conceptual lineage of dynamic documents begins with Vannevar Bush's seminal essay "As We May Think," published in The Atlantic Monthly in July 1945. Bush, then director of the U.S. Office of Scientific Research and Development, proposed a device he called the "memex"—a mechanized desk that would store an individual's books, records, and communications on microfilm, accessible through associative trails.

Bush wrote: "Wholly new forms of encyclopedias will appear, ready-made with a mesh of associative trails running through them." His insight was that information should be linked by association rather than isolated in hierarchical filing systems. While the memex was conceived as an analog microfilm device, its conceptual architecture—personal knowledge bases with associative connections—anticipated hypertext, the World Wide Web, and modern knowledge management systems.

Crucially, Bush recognized that static information becomes stale: "There is a growing mountain of research. But there is increased evidence that we are being bogged down today as specialization extends. The investigator is staggered by the findings and conclusions of thousands of other workers—conclusions which he cannot find time to grasp, much less to remember, as they appear."

The memex was designed to address this problem through dynamic connection rather than static copying.

2.2 Douglas Engelbart and Augmenting Human Intellect (1962-1968)

Douglas Engelbart, profoundly influenced by Bush's essay, dedicated his career to building systems that augmented human intellectual capability. His 1962 report "Augmenting Human Intellect: A Conceptual Framework" laid the theoretical foundation, and his NLS (oN-Line System) provided the first working implementation.

On December 9, 1968, Engelbart presented what became known as "The Mother of All Demos" at the Fall Joint Computer Conference in San Francisco. In ninety minutes, he demonstrated the computer mouse, hypertext linking, real-time collaborative editing, video conferencing, and window-based interfaces—technologies that would take decades to reach mainstream adoption.

Engelbart's key contribution to the Smart Markdown concept was his demonstration that documents could be alive—responsive to user interaction, connected to other documents, and capable of real-time updating. His NLS system allowed multiple users to edit shared documents simultaneously, with changes propagating instantly. The boundary between "finished document" and "dynamic system" dissolved.

2.3 Ted Nelson, Xanadu, and Transclusion (1960-present)

Ted Nelson coined the term "hypertext" in 1963 and published it in 1965 in a paper for the Association for Computing Machinery. His Project Xanadu, begun in 1960 and still under development, represents the most ambitious vision for interconnected digital documents ever conceived.

Nelson's concept of transclusion is central to Smart Markdown's theoretical foundation. He defined transclusion as "a maintained connection between parts which are the same"—in contrast to a link, which is "a connection between things which are different." When content is transcluded rather than copied, changes to the original automatically propagate to all instances.

Nelson wrote: "All digital copies implicitly refer to an original. Why cannot the connection to the original be maintained? Multiple copies, or other approximations to the correct relation, is a crude simulation."

The World Wide Web, as implemented by Tim Berners-Lee, did not incorporate transclusion. Nelson has been critical of this omission: "HTML is precisely what we were trying to PREVENT—ever-breaking links, links going outward only, quotes you can't follow to their origins, no version management, no rights management."

Smart Markdown represents a modest implementation of transclusion principles within the constraints of conventional web infrastructure. While it cannot achieve Nelson's full vision of bidirectional links and origin tracking, it does ensure that referenced values remain synchronized with their authoritative sources.

2.4 Synthesis: From Vision to Implementation

The hypertext pioneers shared a common frustration: information systems that required manual synchronization were fundamentally flawed. Bush worried about researchers buried under mountains of disconnected findings. Engelbart built systems where documents stayed alive and collaborative. Nelson envisioned a "docuverse" where all content maintained connections to its origins.

Smart Markdown takes one small piece of this vision—dynamic variable substitution—and implements it in a practical, lightweight manner suitable for personal publishing systems. It does not solve the grand problems of version management, bidirectional linking, or micropayment tracking. It simply ensures that a document saying "this blog contains {{essay_count}} essays" remains true tomorrow, next month, and next year.

3. Smart Markdown Specification

3.1 Design Philosophy

Smart Markdown adheres to the following principles:

1. Human-readable source: Content stored in the database should remain legible to humans. The token {{essay_count}} is self-documenting.

2. Graceful degradation: Unknown tokens should pass through unchanged rather than causing errors. If {{undefined_variable}} appears in content, it renders as literal text.

3. Render-time resolution: Substitution occurs when content is displayed, not when content is stored. This ensures values are always current.

4. Minimal footprint: Implementation should require minimal code changes to existing systems.

5. Extensibility: Adding new variables should be straightforward.

3.2 Syntax

Variables are enclosed in double curly braces:

{{variable_name}}

Variable names consist of lowercase letters, numbers, and underscores. Names are case-sensitive.

Valid tokens:

• {{essay_count}}
• {{days_since_launch}}
• {{word_count}}
• {{latest_essay_title}}

Invalid tokens:

• {{Essay Count}} (spaces not permitted)
• {{WORD_COUNT}} (uppercase not matched)
• {{ essay_count }} (internal spaces not permitted)

3.3 Initial Variable Set

3.4 Example Usage

Markdown source:

Welcome to Coffee with Claude. Over {{days_since_launch}} days, this practice 
has produced {{essay_count}} essays and {{word_count}} words exploring 
ecological observation, human-AI collaboration, and the nature of memory.

The most recent essay is "{{latest_essay_title}}."

Rendered output (as of December 5, 2025):

Welcome to Coffee with Claude. Over 37 days, this practice has produced 
29 essays and 61,247 words exploring ecological observation, human-AI 
collaboration, and the nature of memory.

The most recent essay is "The Nuts and Bolts Guide to Reverse Engineering 
Ideas and Memories."

4. Implementation Architecture

4.1 Processing Pipeline

Smart Markdown processing must occur BEFORE markdown-to-HTML conversion:

[Database Content] 
    → Smart Markdown Parser (substitute tokens)
    → Markdown Parser (convert to HTML)
    → [Rendered Output]

If the order is reversed, tokens may be partially converted to HTML before substitution, causing malformed output.

4.2 Parser Function

/**
 * Process Smart Markdown tokens in content
 * 
 * @param string $content  Raw markdown content with {{tokens}}
 * @param mysqli $conn     Database connection
 * @return string          Content with tokens replaced by current values
 */
function process_smart_markdown($content, $conn) {
    // Define variable resolvers
    $variables = [
        'essay_count' => function($conn) {
            $sql = "SELECT COUNT(*) as count FROM posts 
                    WHERE status='published' AND visibility='visible'";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return $row['count'];
        },

        'days_since_launch' => function($conn) {
            $launch = new DateTime(CWC_LAUNCH_DATE);
            $now = new DateTime();
            return $now->diff($launch)->days;
        },

        'word_count' => function($conn) {
            $sql = "SELECT SUM(word_count) as total FROM posts 
                    WHERE status='published' AND visibility='visible'";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return number_format($row['total'] ?? 0);
        },

        'latest_essay_title' => function($conn) {
            $sql = "SELECT title FROM posts 
                    WHERE status='published' AND visibility='visible' 
                    ORDER BY published_date DESC LIMIT 1";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return $row['title'] ?? '';
        },

        'latest_essay_url' => function($conn) {
            $sql = "SELECT slug FROM posts 
                    WHERE status='published' AND visibility='visible' 
                    ORDER BY published_date DESC LIMIT 1";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return '/post.php?slug=' . ($row['slug'] ?? '');
        },

        'tag_count' => function($conn) {
            $sql = "SELECT COUNT(DISTINCT tag_id) as count FROM post_tags";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return $row['count'];
        },

        'citation_count' => function($conn) {
            $sql = "SELECT COUNT(*) as count FROM post_citations";
            $result = mysqli_query($conn, $sql);
            $row = mysqli_fetch_assoc($result);
            return $row['count'];
        }
    ];

    // Find and replace all {{tokens}}
    $pattern = '/\{\{(\w+)\}\}/';
    $content = preg_replace_callback($pattern, function($matches) use ($variables, $conn) {
        $var_name = $matches[1];
        if (isset($variables[$var_name])) {
            return $variables[$var_name]($conn);
        }
        return $matches[0]; // Return unchanged if unknown variable
    }, $content);

    return $content;
}

4.3 Configuration

Add launch date constant to config.php:

// Smart Markdown configuration
define('CWC_LAUNCH_DATE', '2025-10-29');

4.4 Integration Points

The parser function should be called wherever content is rendered:

post.php (single essay view):

$content = $post['content'];
$content = process_smart_markdown($content, $conn);
$content = parse_markdown($content);

index.php (homepage excerpts):

$excerpt = $post['excerpt'];
$excerpt = process_smart_markdown($excerpt, $conn);

pages.php (static pages like About):

$content = $page['content'];
$content = process_smart_markdown($content, $conn);
$content = parse_markdown($content);

4.5 Word Count Storage

For efficient aggregation, word count should be stored per-post and calculated on save. If not already present, add to the posts table:

ALTER TABLE posts ADD COLUMN word_count INT DEFAULT 0;

Calculate on essay save in admin/essays.php:

$word_count = str_word_count(strip_tags($content));

5. Testing Protocol

5.1 Unit Tests

5.2 Integration Tests

• [ ] Essay count matches actual published post count
• [ ] Days calculation is accurate across timezone boundaries
• [ ] Word count aggregation handles NULL values
• [ ] Markdown rendering functions correctly after substitution
• [ ] Admin preview shows resolved values
• [ ] No performance degradation on page load

6. Future Extensions

6.1 Additional Variables

The architecture supports straightforward addition of new variables:

• {{subscriber_count}} - Newsletter subscriber total
• {{most_used_tag}} - Tag with highest post count
• {{oldest_essay_date}} - Publication date of first essay
• {{random_essay_link}} - For "surprise me" functionality
• {{current_date}} - Formatted current date
• {{current_year}} - For copyright notices

6.2 Conditional Display

Future versions could support conditional rendering:

{{if essay_count > 50}}
This substantial collection...
{{else}}
This growing collection...
{{endif}}

This would require a more sophisticated parser but remains architecturally compatible.

6.3 Cross-Site Variables

For multi-site deployments (e.g., CWC and Digital Naturalist sharing infrastructure), variables could reference other databases:

{{ndn:essay_count}} essays at Digital Naturalist
{{cwc:essay_count}} essays at Coffee with Claude

7. Conclusion

Smart Markdown represents a practical implementation of transclusion principles for personal publishing systems. By embedding dynamic references rather than static values, documents remain accurate without manual maintenance. The implementation is lightweight—a single function addition to existing infrastructure—yet conceptually grounded in the foundational literature of hypertext.

Ted Nelson's full vision of the docuverse remains unrealized. The web we have is not the web he imagined. But within the constraints of conventional infrastructure, Smart Markdown takes one meaningful step: ensuring that documents tell the truth about themselves.

References

Bush, V. (1945). "As We May Think." The Atlantic Monthly, 176(1), 101-108. https://www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/

Engelbart, D. C. (1962). "Augmenting Human Intellect: A Conceptual Framework." Summary Report, Stanford Research Institute, Contract AF 49(638)-1024.

Engelbart, D. C. & English, W. K. (1968). "A Research Center for Augmenting Human Intellect." AFIPS Conference Proceedings of the 1968 Fall Joint Computer Conference, 33, 395-410.

Nelson, T. H. (1965). "Complex Information Processing: A File Structure for the Complex, the Changing and the Indeterminate." ACM '65: Proceedings of the 1965 20th National Conference, 84-100.

Nelson, T. H. (1974). Computer Lib/Dream Machines. Self-published.

Nelson, T. H. (1981). Literary Machines. Self-published.

Nelson, T. H. (1999). "Xanalogical Structure, Needed Now More Than Ever: Parallel Documents, Deep Links to Content, Deep Versioning, and Deep Re-Use." ACM Computing Surveys, 31(4es), Article 33.

Hamilton, M. P. (2025). "CWC Blog Infrastructure Protocol." Canemah Nature Laboratory Protocol CNL-PR-2025-005. https://canemah.org/archive/document.php?id=CNL-PR-2025-005

Document History

End of Technical Note

Permanent URL: https://canemah.org/archive/document.php?id=CNL-TN-2025-006

Cite This Document

Michael P. Hamilton, Ph.D. (2025). "Smart Markdown: Dynamic Variable Substitution for Living Documents." Canemah Nature Laboratory Technical Note CNL-TN-2025-006. https://canemah.org/archive/document.php?id=CNL-TN-2025-006