BlogRenderer API Documentation

BlogRenderer API Documentation

Overview

BlogRenderer is the main rendering class for the blog system. It handles Markdown parsing, HTML generation, and provides security filtering for all output.

Namespace

namespace Blog\Renderer;

Class: BlogRenderer

Constructor

public function __construct()

Initializes the BlogRenderer with default configuration.

Default Configuration:

  • Parser: Parsedown with safe mode enabled
  • Blog Root: Parent directory of the renderer class
  • Config: Loaded from BLOGTITLE</code>, <code>BLOGDESCRIPTION, and BLOG_AUTHOR constants

Public Methods

setConfig(array $config): void

Updates the renderer configuration by merging with existing config.

Parameters:

  • $config (array): Configuration array to merge

Example:

$renderer = new BlogRenderer();
$renderer->setConfig([
    'title' => 'My Blog',
    'description' => 'A custom description'
]);

getConfig(): array

Returns the current renderer configuration.

Returns:

  • (array): Current configuration array containing:

- title (string): Blog title - description (string): Blog description - author (string): Blog author

Example:

$renderer = new BlogRenderer();
$config = $renderer->getConfig();
echo $config['title']; // Blog title

parseMarkdown(string $content): string

Parses Markdown content to HTML with security filtering and LaTeX support.

Parameters:

  • $content (string): Raw Markdown content

Returns:

  • (string): HTML representation of the Markdown content

Features:

  • XSS protection via SecurityFilter
  • LaTeX preservation (inline $...$ and block $$...$$)
  • Safe mode enabled by default (prevents malicious HTML)

Example:

$renderer = new BlogRenderer();
$html = $renderer->parseMarkdown('# Hello World

This is **bold** text.

Inline math: $E = mc^2$

Block math:
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
');

renderDocument(array $data): string

Renders a complete HTML document for a blog article.

Parameters:

  • $data (array): Document data with keys:

- rootPath (string, optional): Relative path to blog root (default: './') - title (string, optional): Article title (default: '无标题') - content (string, optional): HTML content (default: '') - breadcrumbs (array, optional): Breadcrumb navigation items - toc (array, optional): Table of contents array

Returns:

  • (string): Complete HTML document with DOCTYPE, head, body, etc.

Example:

$renderer = new BlogRenderer();
$html = $renderer->renderDocument([
    'rootPath' => '../',
    'title' => 'My Article',
    'content' => '<p>Article content...</p>',
    'toc' => [
        ['id' => 'section-1', 'text' => 'Section 1', 'level' => 1],
        ['id' => 'section-2', 'text' => 'Section 2', 'level' => 1],
    ],
    'breadcrumbs' => [
        ['link' => '../index.php', 'name' => 'Home'],
        ['link' => './index.php', 'name' => 'Category'],
    ]
]);

Includes:

  • HTML5 boilerplate
  • Meta tags (charset, viewport, description)
  • KaTeX CSS and JS for math rendering
  • Highlight.js CSS for code syntax highlighting
  • Responsive layout with TOC sidebar
  • Copy code button functionality
  • Article navigation

renderIndex(array $data): string

Renders a complete HTML document for an index page (listing directories/articles).

Parameters:

  • $data (array): Index data with keys:

- rootPath (string, optional): Relative path to blog root (default: './') - title (string, optional): Page title (default: '首页') - parentLink (string|null, optional): URL to parent directory - directories (array, optional): List of subdirectories - articles (array, optional): List of articles

Returns:

  • (string): Complete HTML document

Example:

$renderer = new BlogRenderer();
$html = $renderer->renderIndex([
    'rootPath' => './',
    'title' => 'My Category',
    'parentLink' => '../index.php',
    'directories' => [
        ['name' => 'Subcategory', 'link' => 'sub/'],
    ],
    'articles' => [
        ['title' => 'Article 1', 'link' => 'article1.html'],
        ['title' => 'Article 2', 'link' 'article2.html'],
    ]
]);

Private Methods

Rendering Helpers

renderHeader(string $rootPath, array $breadcrumbs = []): string

Renders the site header with optional breadcrumbs.

renderArticle(string $title, string $content, array $toc = []): string

Renders the article section with TOC sidebar.

renderTableOfContents(array $toc): string

Renders the table of contents navigation.

renderTocItems(array $items, int $currentLevel): string

Renders TOC items with proper indentation.

renderArticleNav(string $rootPath): string

Renders article navigation (back to index link).

renderFooter(): string

Renders the site footer.

Renders parent directory link if provided.

renderDirectoryList(array $directories): string

Renders directory listing section.

renderArticleList(array $articles): string

Renders article listing section.

renderScripts(string $rootPath): string

Renders JavaScript for code highlighting, math rendering, and TOC functionality.

LaTeX Protection

protectLatex(string $text): string

Temporarily replaces LaTeX delimiters with placeholders before Markdown parsing.

restoreLatex(string $html): string

Restores LaTeX delimiters after Markdown parsing.

Utilities

getCdnUrl(string $url): string

Returns a CDN URL (placeholder for potential CDN proxy logic).

Supported Markdown Features

  • Headers (H1-H6)
  • Paragraphs
  • Lists (ordered and unordered)
  • Code blocks with syntax highlighting
  • Inline code
  • Bold, italic, strikethrough
  • Links and images
  • Blockquotes
  • Tables
  • Horizontal rules
  • Inline math: $E = mc^2$
  • Block math: $$...$$
  • Mermaid diagrams: ``mermaid ... ``

Security Features

  • XSS Protection: All HTML output is escaped via SecurityFilter::escapeHtml()
  • URL Safety: All URLs are validated via SecurityFilter::escapeUrl()
  • Safe Mode: Parsedown runs in safe mode to prevent malicious HTML
  • CDN URLs: External resources loaded from trusted CDNs (jsdelivr, cdnjs)

CDN Dependencies

  • KaTeX (v0.16.9): Math rendering
  • Highlight.js (v11.9.0): Code syntax highlighting
  • Mermaid (v10.9.0): Diagram rendering

Usage Example

<?php
require_once 'vendor/autoload.php';

use Blog\Renderer\BlogRenderer;

// Create renderer
$renderer = new BlogRenderer();

// Configure
$renderer->setConfig([
    'title' => 'My Tech Blog',
    'description' => 'Technical articles and tutorials',
    'author' => 'John Doe'
]);

// Parse Markdown
$markdown = file_get_contents('article.md');
$html = $renderer->parseMarkdown($markdown);

// Render document
echo $renderer->renderDocument([
    'rootPath' => './',
    'title' => 'My Article Title',
    'content' => $html,
    'toc' => [
        ['id' => 'intro', 'text' => 'Introduction', 'level' => 1],
        ['id' => 'setup', 'text' => 'Setup', 'level' => 1],
    ]
]);

See Also

  • BlogContentProcessor - For processing markdown files
  • SecurityFilter - For security filtering
  • Parsedown - For Markdown parsing
← 返回目录