mirror of
https://github.com/waynesutton/markdown-site.git
synced 2026-01-12 04:09:14 +00:00
Export as PDF, Core Web Vitals performance optimizations, Enhanced diff code block rendering and blog post example on codeblocks
This commit is contained in:
Wayne Sutton
222
content/blog/how-to-use-code-blocks.md
Normal file
222
content/blog/how-to-use-code-blocks.md
Normal file
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: "How to Use Code Blocks"
|
||||
description: "A guide to syntax highlighting, diff rendering, and code formatting in your markdown posts."
|
||||
date: "2026-01-07"
|
||||
slug: "how-to-use-code-blocks"
|
||||
published: true
|
||||
tags: ["tutorial", "markdown", "code", "syntax-highlighting"]
|
||||
readTime: "4 min read"
|
||||
featured: false
|
||||
authorName: "Markdown"
|
||||
authorImage: "/images/authors/markdown.png"
|
||||
excerpt: "Learn how to add syntax-highlighted code blocks and enhanced diff views to your posts."
|
||||
docsSection: true
|
||||
docsSectionGroup: "Publishing"
|
||||
docsSectionOrder: 4
|
||||
docsSectionGroupOrder: 2
|
||||
---
|
||||
|
||||
# How to Use Code Blocks
|
||||
|
||||
Code blocks are essential for technical writing. This guide covers standard syntax highlighting and enhanced diff rendering.
|
||||
|
||||
## Basic code blocks
|
||||
|
||||
Wrap code in triple backticks with a language identifier:
|
||||
|
||||
````markdown
|
||||
```javascript
|
||||
function greet(name) {
|
||||
return `Hello, ${name}!`;
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
This renders with syntax highlighting:
|
||||
|
||||
```javascript
|
||||
function greet(name) {
|
||||
return `Hello, ${name}!`;
|
||||
}
|
||||
```
|
||||
|
||||
## Supported languages
|
||||
|
||||
Common languages with syntax highlighting:
|
||||
|
||||
| Language | Identifier |
|
||||
| ---------- | -------------------- |
|
||||
| JavaScript | `javascript` or `js` |
|
||||
| TypeScript | `typescript` or `ts` |
|
||||
| Python | `python` or `py` |
|
||||
| Bash | `bash` or `shell` |
|
||||
| JSON | `json` |
|
||||
| CSS | `css` |
|
||||
| SQL | `sql` |
|
||||
| Go | `go` |
|
||||
| Rust | `rust` |
|
||||
| Markdown | `markdown` or `md` |
|
||||
|
||||
## Code block features
|
||||
|
||||
Every code block includes:
|
||||
|
||||
- **Language label** in the top right corner
|
||||
- **Copy button** that appears on hover
|
||||
- **Theme-aware colors** matching your selected theme
|
||||
|
||||
## Diff code blocks
|
||||
|
||||
For showing code changes, use the `diff` or `patch` language identifier. These render with enhanced diff visualization powered by @pierre/diffs.
|
||||
|
||||
### Basic diff example
|
||||
|
||||
````markdown
|
||||
```diff
|
||||
--- a/config.js
|
||||
+++ b/config.js
|
||||
@@ -1,5 +1,5 @@
|
||||
const config = {
|
||||
- debug: true,
|
||||
+ debug: false,
|
||||
port: 3000
|
||||
};
|
||||
```
|
||||
````
|
||||
|
||||
This renders as:
|
||||
|
||||
```diff
|
||||
--- a/config.js
|
||||
+++ b/config.js
|
||||
@@ -1,5 +1,5 @@
|
||||
const config = {
|
||||
- debug: true,
|
||||
+ debug: false,
|
||||
port: 3000
|
||||
};
|
||||
```
|
||||
|
||||
### Multi-line changes
|
||||
|
||||
```diff
|
||||
--- a/utils.ts
|
||||
+++ b/utils.ts
|
||||
@@ -10,12 +10,15 @@
|
||||
export function formatDate(date: Date): string {
|
||||
- return date.toLocaleDateString();
|
||||
+ return date.toLocaleDateString('en-US', {
|
||||
+ year: 'numeric',
|
||||
+ month: 'long',
|
||||
+ day: 'numeric'
|
||||
+ });
|
||||
}
|
||||
|
||||
export function parseDate(str: string): Date {
|
||||
- return new Date(str);
|
||||
+ const parsed = new Date(str);
|
||||
+ if (isNaN(parsed.getTime())) {
|
||||
+ throw new Error('Invalid date string');
|
||||
+ }
|
||||
+ return parsed;
|
||||
}
|
||||
```
|
||||
|
||||
### Diff view modes
|
||||
|
||||
Diff blocks include a view toggle button:
|
||||
|
||||
- **Unified view** (default): Shows changes in a single column with +/- indicators
|
||||
- **Split view**: Shows old and new code side by side
|
||||
|
||||
Click the toggle button in the diff header to switch between views.
|
||||
|
||||
## Adding new functions
|
||||
|
||||
```diff
|
||||
--- a/api.ts
|
||||
+++ b/api.ts
|
||||
@@ -5,6 +5,14 @@ export async function fetchUser(id: string) {
|
||||
return response.json();
|
||||
}
|
||||
|
||||
+export async function updateUser(id: string, data: UserUpdate) {
|
||||
+ const response = await fetch(`/api/users/${id}`, {
|
||||
+ method: 'PATCH',
|
||||
+ body: JSON.stringify(data)
|
||||
+ });
|
||||
+ return response.json();
|
||||
+}
|
||||
+
|
||||
export async function deleteUser(id: string) {
|
||||
return fetch(`/api/users/${id}`, { method: 'DELETE' });
|
||||
}
|
||||
```
|
||||
|
||||
## Removing code
|
||||
|
||||
```diff
|
||||
--- a/legacy.js
|
||||
+++ b/legacy.js
|
||||
@@ -1,15 +1,8 @@
|
||||
const express = require('express');
|
||||
const app = express();
|
||||
|
||||
-// Old middleware - no longer needed
|
||||
-app.use((req, res, next) => {
|
||||
- console.log('Request:', req.method, req.url);
|
||||
- next();
|
||||
-});
|
||||
-
|
||||
app.get('/', (req, res) => {
|
||||
res.send('Hello World');
|
||||
});
|
||||
|
||||
-// Deprecated route
|
||||
-app.get('/old', (req, res) => res.redirect('/'));
|
||||
-
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
## Inline code
|
||||
|
||||
For inline code, use single backticks:
|
||||
|
||||
```markdown
|
||||
Run `npm install` to install dependencies.
|
||||
```
|
||||
|
||||
Renders as: Run `npm install` to install dependencies.
|
||||
|
||||
Inline code is detected automatically when the content is short (under 80 characters) and has no newlines.
|
||||
|
||||
## Plain text blocks
|
||||
|
||||
Code blocks without a language identifier render as plain text with word wrapping:
|
||||
|
||||
```
|
||||
This is a plain text block. It wraps long lines automatically
|
||||
instead of requiring horizontal scrolling. Useful for logs,
|
||||
output, or any text that isn't code.
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
**Choose the right language**: Use the correct language identifier for accurate highlighting. TypeScript files should use `typescript`, not `javascript`.
|
||||
|
||||
**Keep examples focused**: Show only the relevant code. Long blocks lose readers.
|
||||
|
||||
**Use diffs for changes**: When explaining modifications to existing code, diff blocks clearly show what changed.
|
||||
|
||||
**Test your blocks**: Preview your post to verify syntax highlighting works correctly.
|
||||
|
||||
## Summary
|
||||
|
||||
| Block type | Use case |
|
||||
| ------------------ | ---------------------------------------------- |
|
||||
| Regular code block | Showing code snippets with syntax highlighting |
|
||||
| Diff block | Showing code changes with additions/deletions |
|
||||
| Plain text block | Logs, output, or non-code text |
|
||||
| Inline code | Commands, function names, short references |
|
||||
|
||||
Code blocks make technical content readable. Use the right format for your content type.
|
||||
@@ -11,6 +11,94 @@ docsSectionOrder: 4
|
||||
|
||||
All notable changes to this project.
|
||||
|
||||
## v2.15.0
|
||||
|
||||
Released January 7, 2026
|
||||
|
||||
**Export as PDF**
|
||||
|
||||
Added PDF export option to CopyPageDropdown. Users can now export any blog post or page as a clean, formatted PDF document using the browser's native print dialog.
|
||||
|
||||
**Features:**
|
||||
|
||||
- Export as PDF button in Copy page dropdown (positioned at end of menu)
|
||||
- Clean formatted output without markdown syntax
|
||||
- Title displayed as proper heading
|
||||
- Metadata shown on single line (date, read time, tags)
|
||||
- Content with markdown stripped for readable document
|
||||
- Uses Phosphor FilePdf icon
|
||||
|
||||
**Technical:**
|
||||
|
||||
- Added `formatForPrint` function to strip markdown syntax (headings, bold, italic, code, links, blockquotes)
|
||||
- Added `handleExportPDF` handler that opens styled print window
|
||||
- Imports `FilePdf` from `@phosphor-icons/react` (already installed in project)
|
||||
|
||||
**Files changed:**
|
||||
|
||||
- `src/components/CopyPageDropdown.tsx` - New PDF export functionality
|
||||
|
||||
---
|
||||
|
||||
## v2.14.0
|
||||
|
||||
Released January 7, 2026
|
||||
|
||||
**Core Web Vitals performance optimizations**
|
||||
|
||||
Fixes for PageSpeed Insights failures on mobile and desktop. These changes improve Largest Contentful Paint (LCP) and eliminate non-composited animation warnings.
|
||||
|
||||
**Fixes:**
|
||||
|
||||
- Non-composited animations: Visitor map pulse animations now use GPU-composited `transform: scale()` instead of animating SVG `r` attribute
|
||||
- Duplicate keyframes: Removed 5 redundant `@keyframes spin` definitions from CSS
|
||||
- GPU compositing hints: Added `will-change` to animated elements (theme toggle, dropdown menus, modals, scroll-to-top button)
|
||||
|
||||
**Performance additions:**
|
||||
|
||||
- Critical CSS inlined in index.html (~2KB) for instant first paint
|
||||
- Theme variables, reset styles, layout skeleton, and navigation pre-loaded
|
||||
- Additional preconnect hints for Convex site endpoints
|
||||
|
||||
**Files changed:**
|
||||
|
||||
- `src/styles/global.css` - Animation fixes, will-change hints, removed duplicates
|
||||
- `src/components/VisitorMap.tsx` - Updated SVG circle radius for transform-based animation
|
||||
- `index.html` - Inline critical CSS, resource hints
|
||||
|
||||
---
|
||||
|
||||
## v2.13.0
|
||||
|
||||
Released January 7, 2026
|
||||
|
||||
**Enhanced diff code block rendering**
|
||||
|
||||
Diff and patch code blocks now render with enhanced visualization powered by @pierre/diffs. This brings Shiki-based syntax highlighting specifically designed for showing code changes.
|
||||
|
||||
**Features:**
|
||||
|
||||
- Unified view (default): Single column with +/- indicators
|
||||
- Split view: Side-by-side comparison of old and new code
|
||||
- View toggle button to switch between modes
|
||||
- Theme-aware colors matching dark/light/tan/cloud themes
|
||||
- Copy button for copying raw diff content
|
||||
- Automatic routing: Use ```diff or ```patch in markdown
|
||||
|
||||
**New documentation:**
|
||||
|
||||
- Blog post: "How to Use Code Blocks" with examples of regular code blocks and diff rendering
|
||||
|
||||
**Technical:**
|
||||
|
||||
- Added `@pierre/diffs` package
|
||||
- Created `DiffCodeBlock` component (`src/components/DiffCodeBlock.tsx`)
|
||||
- Updated `BlogPost.tsx` to route diff/patch blocks to new renderer
|
||||
- Added diff block CSS styles to `global.css`
|
||||
- Added `vendor-diffs` chunk to Vite config
|
||||
|
||||
---
|
||||
|
||||
## v2.12.0
|
||||
|
||||
Released January 7, 2026
|
||||
|
||||
Reference in New Issue
Block a user