pages/.github/instructions/markdown-content.instructions.md

applyTo
_books/**/*.md,_news/**/*.md,_pages/**/*.md,_posts/**/*.md,_projects/**/*.md,_teachings/**/*.md

Content Files (Markdown) Instructions

File Organization

Content in al-folio is organized by type:

• _books/ – Book reviews and summaries
• _news/ – News/announcements
• _pages/ – Static pages (about, CV, publications, projects, etc.)
• _posts/ – Blog posts (format: YYYY-MM-DD-title.md)
• _projects/ – Project showcase entries
• _teachings/ – Course and teaching information

Frontmatter Structure

Every markdown file requires YAML frontmatter at the top. The structure varies by content type.

Book Frontmatter (_books/)

---
layout: book-review
title: Book Title
author: Book Author Name
publisher: Publisher Name
year: 2023
rating: 8/10
img: /assets/img/book-cover.jpg
---

News Frontmatter (_news/)

---
layout: post
title: News Title
date: YYYY-MM-DD
---

Page Frontmatter (_pages/)

---
layout: page
title: Page Title
permalink: /pathname/
description: Brief description for metadata
---

Blog Post Frontmatter (_posts/)

---
layout: post
title: Post Title
date: YYYY-MM-DD
categories: category-name
description: Brief description
---

Important: Post filenames MUST follow format: YYYY-MM-DD-title.md (hyphen-separated words)

Project Frontmatter (_projects/)

---
layout: page
title: Project Name
description: Short description
img: /assets/img/project-image.jpg
importance: 1
---

Teaching/Course Frontmatter (_teachings/)

---
layout: page
title: Course Title
description: Course description
---

Special Frontmatter Fields

For Books

• author: Author name or comma-separated list
• publisher: Publisher name
• year: Publication year
• rating: Personal rating (e.g., 8/10)
• img: Path to book cover image (/assets/img/...)

For Blog Posts

• categories: Tag for post organization (single word, no spaces)
• related_posts: Set to false to disable related posts display (useful for short posts)

For Projects

• importance: Integer (1, 2, 3...) – higher = featured first
• img: Path to thumbnail image (/assets/img/...)
• featured: Set to true to display on main projects section

Date Format

Always use ISO 8601: YYYY-MM-DD (e.g., 2023-12-25)

Markdown Content

Basic Markdown Syntax

# Heading 1

## Heading 2

### Heading 3

**bold text**
_italic text_
`inline code`

- List item 1
- List item 2

[Link text](https://url.com)

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

al-folio-Specific Features

Includes/Shortcodes

• {% include figure.liquid ... %} – Responsive images with captions
• {% include audio.liquid ... %} – Audio player
• {% include video.liquid ... %} – Video player
• {% include bib_search.liquid ... %} – Bibliography search
• {% include calendar.liquid ... %} – Event calendar

Math Support

Inline: $E = mc^2$

Display mode:
$$\int_0^1 f(x) dx$$

Code Blocks

```python
def hello():
    print("Hello, world!")
```

Blockquotes

> This is a quote
>
> > Nested quote

Jekyll Features Available

• Liquid variables: {{ site.title }}, {{ page.title }}
• Collections: {{ site.posts }}, {{ site.projects }}
• Filters: | date: format, | where: key value
• Tags: {% if condition %} ... {% endif %}

Common Content Patterns

Creating a Blog Post

1. Create file: _posts/YYYY-MM-DD-my-post.md
2. Add frontmatter with layout: post, title, date, categories
3. Write markdown content
4. Test: docker compose up → http://localhost:8080/blog
5. Post will appear in reverse chronological order

Creating a Project Entry

1. Create file: _projects/project-name.md
2. Add frontmatter with layout: page, title, description, img, importance
3. Write markdown content describing the project
4. Test: docker compose up → http://localhost:8080/projects

Adding Images

{% include figure.liquid path="/assets/img/example.jpg" title="Image caption" %}

Linking to Other Pages

[About Me](/about/)
[My CV](/cv/)
[Blog Post]({% link _posts/2023-01-15-my-post.md %})

Testing & Validation

Before Committing

1. Frontmatter syntax: Verify YAML is valid (no unclosed quotes, proper indentation)
2. Date format: Check YYYY-MM-DD format is correct
3. Build test:

   docker compose down
   docker compose up
   # Wait for "Server running" message
   # Navigate to your content in browser
   # Verify formatting, images, and links work
   

Common Issues

• Post not appearing: Check date is today or earlier, filename format is correct
• Images not loading: Verify path starts with /assets/, file exists
• Related posts error: Content has no meaningful words; add more text or set related_posts: false

File Naming Conventions

Blog Posts

• Format: YYYY-MM-DD-title-with-hyphens.md
• Example: 2023-12-25-christmas-post.md
• Words separated by hyphens, no spaces

Projects

• Format: project-name.md
• Example: my-research-project.md
• Use hyphens for readability

Pages

• Format: descriptive-name.md
• Example: about.md, teaching.md, cv.md

Markdown Linting & Formatting

The Prettier formatter applies to markdown files:

• Line length: Soft wrap at 88 characters
• Lists: Consistent bullet formatting
• Code blocks: Proper fence syntax
• Spacing: Consistent blank lines

Always run before committing:

npx prettier --write .

Trust These Instructions

When creating or editing content:

• Follow the frontmatter structure for your content type
• Test locally with docker compose up to verify appearance
• Check date format, filename format, and image paths
• Only search for advanced features if frontmatter or markdown error messages appear