Back to Documentation

Unified Markdown Content System

A standardized approach for creating, managing, and displaying art and code projects using Markdown.

Overview

This project establishes a unified content creation system based on Markdown that works seamlessly across different content types:

  • Art projects
  • Code projects
  • Future extensions (blogs, news articles, etc.)

The primary goal is to maintain consistency in how content is authored while providing flexible display options that adapt to the specific needs of each content type.

Why Markdown?

Markdown provides several advantages for our unified content system:

  • Simplicity: Easy to learn and use with minimal markup
  • Readability: Readable in plain text, even without rendering
  • Portability: Content can be moved between platforms without losing formatting
  • Version control: Works well with Git and other version control systems
  • Future-proof: Plain text format ensures long-term accessibility
  • Wide adoption: Supported by many tools and platforms
  • Extensibility: Can be enhanced with various extensions for specific needs

Content Structure

Directory Organization

/content/
  /art/
    project1.md
    project2.md
    /media/
      image1.jpg
      video1.mp4
  /code/
    project1.md
    project2.md
    /snippets/
      snippet1.md
      snippet2.md

Document Structure

Each content file follows a consistent format:

---
title: Project Title
date: YYYY-MM-DD
tags: [tag1, tag2, tag3]
thumbnail: path/to/thumbnail.jpg
---

# Project Title

## Introduction

Project description and overview.

## Content Section

Content with **formatting**, [links](https://example.com), and other elements.

![Image description](path/to/image.jpg)

## Code Examples

```language
code snippet here

Media

{{< include media/video1.mp4 >}}


## Media Integration

### Images

Standard Markdown syntax:
```markdown
![Image description](path/to/image.jpg)

With optional attributes:

![Image description](path/to/image.jpg){width=500px class="centered"}

Videos

Videos can be embedded using custom shortcodes:

{{< video src="path/to/video.mp4" autoplay=true loop=true >}}

Audio

Audio files can be embedded similarly:

{{< audio src="path/to/audio.mp3" controls=true >}}

Code Integration

Inline Code

For short code references:

Use the `print()` function to display text.

Code Blocks

For longer code examples:

```python
def hello_world():
    print("Hello, World!")
```

External Code Snippets

To include code from external files:

{{< include-code path="path/to/snippet.md" >}}

Or reference specific parts of a file:

{{< include-code path="path/to/file.js" lines="10-20" >}}

Workflow

  1. Create content using any text editor in Markdown format
  2. Store media files in the appropriate media directory
  3. Link to media and code snippets using relative paths
  4. Preview content using a Markdown renderer
  5. Commit changes to version control
  6. Publish through the automated build process

Integration with Existing Website

This Markdown system integrates with the existing Astro.js-based portfolio:

  1. Content Source: Markdown files serve as the single source of truth for all content
  2. Build Process: During the Astro build process, Markdown is processed into HTML
  3. Component Integration: Custom Astro components can be used within MDX for enhanced functionality
  4. Consistent Styling: TailwindCSS classes can be applied within the Markdown using custom attributes

Best Practices

  1. Consistency: Follow the established templates and patterns
  2. Media optimization: Compress images and videos before adding them
  3. Reusability: Create reusable snippets for common elements
  4. Version control: Commit meaningful changes with descriptive messages
  5. Metadata: Always include proper frontmatter with all required fields
  6. Link checking: Ensure all links work before publishing
  7. Accessibility: Provide alt text for images and captions for non-text content

Tools and Resources

  • Editors: VS Code with Markdown extensions, Typora, Obsidian
  • Preview: Local development server with hot reload
  • Conversion: Pandoc for converting to other formats when needed
  • Extensions: GitHub Flavored Markdown, Mermaid diagrams, MathJax

Implementation Plan

  1. Set up the content directory structure (building on existing src/content directory)
  2. Create templates for different content types
  3. Implement the Markdown renderer with necessary extensions
  4. Develop the media integration components
  5. Build the code snippet integration system
  6. Create the preview and publishing workflow
  7. Document the system for content creators

References