DEV Community: Nicholas Ma

The Secret Language Between You and AI

Nicholas Ma — Mon, 31 Aug 2026 15:46:10 +0000

Every time you ask ChatGPT a question or Claude for help, they answer in the same format. Not English. Not code. Something in between.

It's called Markdown. You've seen it — hash symbols for headings, double stars for bold, dashes for lists. It looks like broken formatting, but it's not. It's a deliberate format, and it's everywhere now.

What Is Markdown?

Markdown is plain text with a few formatting symbols. Created by John Gruber in 2004. The idea was simple: write formatted documents that are still readable as raw text.

No menus, no toolbars. Just a handful of symbols:

Hash makes a heading
Double stars make bold
Single stars make italic
Dashes start bullet points
Brackets with parentheses make links
Greater-than sign starts a quote

Save it as a .md file and any Markdown app renders it. Open it in Notepad and it's still readable. That's the whole appeal.

Why Every AI Uses It

AI tools need a format that's plain text, human-readable, and machine-parseable. Markdown is the obvious choice — it's the only widely-used format that checks all three.

That's why ChatGPT, Claude, Gemini, Copilot, and Cursor all default to Markdown output. When they write you a guide, it's Markdown headings and lists. When they show code, it's Markdown code blocks. It's not a coincidence — it's the only format that makes sense for text-based AI output.

It's Not Just for AI

Markdown was a developer niche five years ago. Now it's the default format for:

AI tools — ChatGPT, Claude, Gemini all output it
Note-taking — Notion, Obsidian, Bear
Code platforms — GitHub, GitLab READMEs and issues
Chat apps — Discord, Slack, Telegram formatting
Blogging — Ghost, Jekyll, Hugo, Dev.to, Hashnode
Data science — Jupyter notebooks

If you work in tech, you're already surrounded by Markdown. The question is whether you can read it fluently or just squint at it.

The Basics (5 Minutes)

You don't need to learn everything. Six patterns cover 90% of it:

Headings — One hash for big, two for medium, three for small.

Bold/italic — Double stars for bold, single for italic.

Lists — Dashes for bullets. Numbers with periods for ordered lists. Indent to nest.

Links — Square brackets around text, parentheses around URL.

Code — Single backticks for inline code. Triple backticks for code blocks.

Quotes — Greater-than sign at the start of a line.

That's enough to read any AI response, write a README, or format a message in Slack.

What You Can Do With It

Better AI prompts. Give AI structured input — headings, bullet points, numbered steps — and you get structured output back. The format of your prompt shapes the format of the answer.

Future-proof notes. Markdown files are plain text. They'll open on any device in 10 years. No vendor lock-in, no proprietary format.

Professional documents. One .md file can become PDF, Word, HTML, LaTeX, or an image. LoveMarkdown does this for free — I use it when someone asks for a PDF and I don't want to deal with Word.

Developer communication. GitHub issues, pull requests, API docs — it's all Markdown. Knowing it means you can participate without asking how to format things.

Getting Started

Open any text editor. Write something using the six patterns above. Save as .md. You just wrote Markdown.

If you want a better experience, VS Code has a built-in preview, Obsidian shows live rendering, and Dillinger works in your browser.

Or just ask ChatGPT to write something. Everything it outputs is Markdown — read it, and you'll pick up the patterns fast.

Want the full picture? This markdown guide covers the history, syntax, and all the flavors in depth.

How I Built a Markdown Converter with Next.js 16 & Cloudflare Workers

Nicholas Ma — Sun, 30 Aug 2026 16:06:46 +0000

I've always been frustrated by existing Markdown converters. They either slap watermarks on your PDFs, require sign-ups, or charge you for basic features. So I built LoveMarkdown.And it runs entirely on Cloudflare Workers.

Here's the technical breakdown of how it works and the decisions I made along the way.

The Architecture

┌─────────────────────────────────────────────┐
│            Cloudflare Workers                │
│  ┌─────────────────────────────────────┐    │
│  │         Next.js 16 (App Router)      │    │
│  │  ┌──────────┐  ┌──────────────────┐ │    │
│  │  │  SSR     │  │  Client-Side     │ │    │
│  │  │  Pages   │  │  Conversion      │ │    │
│  │  └──────────┘  └──────────────────┘ │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
   Static Assets        Browser APIs
   (highlight.js,      (html2canvas,
    KaTeX CSS)          File API, Blob)

The key insight: all conversion happens client-side. No server uploads, no privacy concerns. The user's Markdown never leaves their browser.

Next.js 16 App Router Setup

This was my first real project with Next.js 16's App Router. The routing is file-based, so each converter gets its own route:

src/app/
├── page.tsx                    # Landing page
├── markdown-to-pdf/page.tsx    # MD → PDF
├── markdown-to-word/page.tsx   # MD → Word
├── markdown-to-html/page.tsx   # MD → HTML
├── markdown-to-latex/page.tsx  # MD → LaTeX
├── pdf-to-markdown/page.tsx    # PDF → MD
├── html-to-markdown/page.tsx   # HTML → MD
├── word-to-markdown/page.tsx   # Word → MD
└── layout.tsx                  # Shared layout

Each route uses a shared MarkdownEditor component that handles the split-pane UI (edit left, preview right) and export buttons.

The Conversion Pipeline

Markdown → HTML

I use marked for parsing with highlight.js for syntax highlighting. The tricky part was math support — KaTeX expressions like $E = mc^2$ would get mangled by the Markdown parser.

My solution: extract math before parsing, restore after.

function extractMath(md: string): { md: string; placeholders: string[] } {
  const placeholders: string[] = [];

  // Extract display math ($$...$$) first
  let processed = md.replace(/\$\$([\s\S]+?)\$\$/g, (_match, math) => {
    const idx = placeholders.length;
    placeholders.push(`display:${encodeURIComponent(math.trim())}`);
    return `%%MATH_${idx}%%`;
  });

  // Extract inline math ($...$)
  processed = processed.replace(
    /(?<!\$)\$(?!\$)(.+?)(?<!\$)\$(?!\$)/g,
    (_match, math) => {
      const idx = placeholders.length;
      placeholders.push(`inline:${encodeURIComponent(math.trim())}`);
      return `%%MATH_${idx}%%`;
    }
  );

  return { md: processed, placeholders };
}

The placeholders survive marked.parse() untouched, then I swap them back with KaTeX-rendered HTML.

Markdown → PDF

This was the hardest part. I went through three approaches:

Server-side PDF generation — required file uploads, privacy issues
Print-to-PDF via window.print() — inconsistent across browsers
html2canvas + jsPDF — the winner

The trick is rendering the HTML into an off-screen <div>, capturing it with html2canvas, then embedding the image into a PDF with html2pdf.js:

const container = document.createElement("div");
container.innerHTML = `<style>${baseStyles}</style>${bodyHtml}`;

// Apply inline styles — html2canvas ignores <style> blocks
applyInlineStyles(container, template);

// Fix code blocks: expand to show ALL content
container.querySelectorAll("pre").forEach((pre) => {
  pre.style.setProperty("overflow", "visible", "important");
  pre.style.setProperty("white-space", "pre", "important");
});

document.body.appendChild(container);

await html2pdf()
  .set({
    margin: [0.75, 0.5, 0.75, 0.5],
    filename,
    html2canvas: { scale: 2, useCORS: true },
    jsPDF: { unit: "in", format: "letter", orientation: "portrait" },
    pagebreak: {
      mode: ["avoid-all", "css", "legacy"],
      avoid: ["pre", "blockquote", "table", "tr", "h1", "h2", "h3"],
    },
  })
  .from(container)
  .save();

The pagebreak.avoid config is critical — without it, code blocks get sliced in half at page boundaries.

Markdown → Word

For Word export, I use the docx library to build a .docx file programmatically. The challenge is mapping Markdown elements to Word's paragraph/heading/run model.

PDF → Markdown

Reverse conversion uses pdfjs-dist to extract text, then applies heuristics to detect headings (all-caps lines under 80 chars become ## headings):

const trimmed = line.trim();
if (trimmed === trimmed.toUpperCase() && trimmed.length < 80 && trimmed.length > 3) {
  return `## ${trimmed}`;
}

It's not perfect — real-world PDFs are messy — but it handles most documents reasonably well.

Template System

I built a template system with 10 hand-tuned document styles (Classic, Minimal, Academic, etc.) and 3 density presets (Compact, Standard, Relaxed). Each template defines colors, fonts, font sizes, and spacing:

interface Template {
  id: string;
  name: string;
  colors: {
    heading: string;
    text: string;
    link: string;
    codeBackground: string;
    // ... 12 more color tokens
  };
  fonts: { heading: string; body: string; code: string };
  fontSizes: { h1: number; h2: number; /* ... */ body: number; code: number };
  spacing: { headingBefore: number; headingAfter: number; /* ... */ };
}

The same template drives the live preview, PDF output, Word output, and Google Docs export — one source of truth for all formats.

Deploying to Cloudflare Workers with OpenNext

This is where things got interesting. Cloudflare Workers don't support Node.js APIs natively, so you can't just next build && next start. You need OpenNext to adapt the build.

The build script handles the chicken-and-egg problem:

// scripts/cf-build.js
if (process.env.OPENNEXT_PARENT === "1") {
  // Inner call: plain Next.js build
  run("npx", ["next", "build"]);
} else {
  // Outer call: OpenNext build
  run("npx", ["opennextjs-cloudflare", "build"], {
    ...process.env,
    OPENNEXT_PARENT: "1",
  });
}

Why the guard? opennextjs-cloudflare build internally re-runs npm run build for the Next.js step. If build pointed at OpenNext itself, you'd get infinite recursion. The OPENNEXT_PARENT env var marks the inner invocation so it only runs next build.

The deploy pipeline is simple:

npm run build          # Produces .open-next/ artifact
npx wrangler deploy    # Push to Cloudflare

Key Libraries

Library	Purpose
`marked`	Markdown → HTML parsing
`highlight.js`	Syntax highlighting
`katex`	LaTeX math rendering
`html2canvas`	DOM → canvas capture
`html2pdf.js`	Canvas → PDF generation
`docx`	Word document generation
`pdfjs-dist`	PDF text extraction
`mammoth`	Word → HTML conversion
`turndown`	HTML → Markdown conversion

Lessons Learned

Inline everything for html2canvas. It ignores <style> blocks — you must set styles directly on elements via setAttribute("style", ...).
KaTeX needs pre-processing. Don't let the Markdown parser touch LaTeX syntax. Extract placeholders first, render after.
Page breaks are hard. The pagebreak config in html2pdf.js needs mode: ["avoid-all", "css", "legacy"] to actually work. Without "avoid-all", the avoid list is ignored.
Cloudflare Workers + Next.js is doable but quirky. The OpenNext adapter handles most edge cases, but you need to understand the build pipeline to debug issues.
Client-side conversion = zero server cost. The entire app is static assets served from Cloudflare's edge. No API calls, no server processing.

Try It

If you want to convert Markdown to anything, check out LoveMarkdown. Works with:

Source code is not open-source yet, but I'm considering it. Questions? Drop them in the comments.

Building a 9-Language Fan Site with Next.js 15 and next-intl (No Middleware)

Nicholas Ma — Sat, 22 Aug 2026 06:19:16 +0000

I recently built a multilingual fan site for The Duskbloods, an upcoming FromSoftware game. The challenge: 9 languages (English, Japanese, Korean, Chinese, Spanish, French, German, Italian, Portuguese), static generation, and no middleware — all deployed on Cloudflare Workers.

Here's how I did it and what I learned.

The Architecture

The site uses Next.js 15 App Router with next-intl v4 for internationalization. The key constraint: I wanted to avoid middleware to keep Cloudflare Worker costs down.

src/
├── app/
│   ├── (root)/          # English at /
│   │   ├── gameplay/
│   │   ├── characters/
│   │   └── ...
│   └── [locale]/        # Other languages at /zh, /ja, /ko...
│       ├── gameplay/
│       ├── characters/
│       └── ...
├── messages/            # Translation files
│   ├── en.json
│   ├── ja.json
│   ├── zh.json
│   └── ...
└── components/          # Shared components
    └── views/

Route Groups for Language Separation

Instead of using middleware to detect locale, I use route groups:

(root) — English content at the root path /
[locale] — Other languages at /zh, /ja, /ko, etc.

This means English gets clean URLs (/gameplay) while other languages get prefixed URLs (/zh/gameplay). Good for SEO — English is the default, and other languages have clear URL signals.

Why No Middleware?

Cloudflare Workers charge per request. Middleware runs on every request. For a static site with 9 languages, that's 9x the middleware invocations for every page load. By handling locale in the route, I skip middleware entirely.

// src/app/[locale]/layout.tsx
export async function generateStaticParams() {
  return ['ja', 'zh', 'ko', 'es', 'fr', 'de', 'it', 'pt'].map(locale => ({ locale }));
}

This pre-generates all locale variants at build time. Zero runtime locale detection.

The Translation System

Message Files

Each locale has a JSON message file:

// src/messages/zh.json
{
  "gameplay": {
    "intro": {
      "eyebrow": "玩法介绍",
      "title": "游戏机制",
      "lead": "深入了黄昏征讨的核心机制。"
    },
    "virtue": {
      "title": "美德",
      "types": [
        {"title": "讨伐之美德", "desc": "黄昏之地会出现特别强力的敌人..."},
        {"title": "灯之美德", "desc": "点亮分布在黄昏之地中..."}
      ]
    }
  }
}

Components Are Language-Agnostic

The same view component renders all languages — only the message file changes:

// src/components/views/GameplayView.tsx
export default function GameplayView() {
  const t = useTranslations('gameplay');

  return (
    <section>
      <h2>{t('intro.title')}</h2>
      <p>{t('intro.lead')}</p>
    </section>
  );
}

Handling Structured Content

For arrays and objects, I use t.raw():

const types = t.raw('virtue.types') as VirtueType[];

return (
  <div>
    {types.map((v, i) => (
      <div key={i}>
        <h3>{v.title}</h3>
        <p>{v.desc}</p>
      </div>
    ))}
  </div>
);

Optional Sections with Safe Loading

Some content exists in some languages but not others. I created a safeLoad helper:

function safeLoad<T>(key: string, check: (r: unknown) => boolean): T | null {
  try {
    const raw = t.raw(key) as unknown;
    return check(raw) ? (raw as T) : null;
  } catch { return null; }
}

const virtue = safeLoad<VirtueData>('virtue', (r) =>
  !!r && typeof r === 'object' && 'types' in r && Array.isArray((r as any).types));

// In JSX:
{virtue && <section>...</section>}

This way, sections gracefully degrade when translations are missing.

Content Sourcing

The game has an official gameplay guide in 9 languages. I fetched each version and extracted structured content:

import requests, re, json

guides = {
    "en": "https://.../lang=en",
    "ja": "https://.../lang=ja",
    "ko": "https://.../lang=ko",
    # ...
}

for locale, url in guides.items():
    html = requests.get(url).text
    # Extract h3 headings and their descriptions
    items = extract_h3_with_desc(html)
    # Write to message file
    update_message_file(locale, items)

This gave me official translations for all 9 languages — no machine translation needed.

External Images

The game's official CDN hosts screenshots and gameplay images. I reference them directly:

const GGBASE = 'https://media.fromsoftware.jp/theduskbloods/campaign/resources/networktest/images/gameplayguide';

const virtueImages = [
  `${GGBASE}/virtue/pc/img_01.jpg`,
  `${GGBASE}/virtue/pc/img_02.jpg`,
  // ...
];

No need to host images myself. The CDN is fast and reliable.

Deployment on Cloudflare Workers

I use OpenNext to build for Cloudflare:

npx opennextjs build
npx wrangler deploy

The build outputs static HTML for all 9 language variants. Cloudflare serves them globally with zero cold starts.

SEO Considerations

Sitemap

// src/app/sitemap.ts
export default function sitemap() {
  const pages = ['', '/gameplay', '/characters', '/gallery', '/network-test'];
  const locales = ['zh', 'ja', 'ko', 'es', 'fr', 'de', 'it', 'pt'];

  return [
    ...pages.map(path => ({ url: `https://duskbloods.net${path}`, priority: 0.8 })),
    ...locales.flatMap(locale =>
      pages.map(path => ({
        url: `https://duskbloods.net/${locale}${path}`,
        priority: 0.7,
      }))
    ),
  ];
}

Structured Data

Each page includes JSON-LD breadcrumbs:

const breadcrumbLd = {
  '@context': 'https://schema.org',
  '@type': 'BreadcrumbList',
  itemListElement: [
    { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://duskbloods.net' },
    { '@type': 'ListItem', position: 2, name: 'Gameplay', item: 'https://duskbloods.net/gameplay' },
  ],
};

What I Learned

Route groups > middleware for static multilingual sites. Simpler, cheaper, better for SEO.
t.raw() is your friend. Don't try to translate arrays with t() — use t.raw() and type the result.
Safe loading prevents crashes. Missing translations shouldn't break the build. Use try/catch and null checks.
Official translations beat machine translation. If the content exists in multiple languages from the source, use it.
Cloudflare Workers + OpenNext works well for static multilingual sites. No cold starts, global CDN, reasonable cost.

The site is live at duskbloods.net with all 9 languages fully translated. The code is a standard Next.js 15 project — if you're building something similar, the patterns above should work for you.

Questions or suggestions? Drop a comment below.

Eight locales and no server: internationalizing a static Next.js site

Nicholas Ma — Fri, 14 Aug 2026 10:39:38 +0000

Last month I rebuilt a small website I run. Static export, eight languages, hosted on Cloudflare Pages — free, fast, and nothing to patch.
The catch: static export and i18n don't fight each other, but they change how you think about a few things. Here's what I ended up with and the parts that weren't obvious at first.

The stack

Next.js 15 with next-intl 4, React 18, all of it prerendered with output: 'export'. No middleware, no server functions. Every page becomes a real HTML file at build time.

// next.config.js
import { withNextIntl } from 'next-intl/plugin';
const nextConfig = {
  output: 'export',
  images: { unoptimized: true },
};
export default withNextIntl(nextConfig);

The images.unoptimized flag is the first hint that static export has opinions. There's no image pipeline when there's no server, so next/image needs to be told to leave files alone.

Locale from the URL, not the request

On a server you'd typically read Accept-Language and pick a locale per request. With static export there's no request to inspect. The locale has to come from the URL itself, and every locale needs to be a separate set of prerendered files.
I defined the routing with one deliberate choice:

// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';
export const routing = defineRouting({
  locales: ['en', 'de', 'ja', 'ko', 'es', 'fr', 'pt', 'it'],
  defaultLocale: 'en',
  localePrefix: {
    mode: 'always',
    prefixes: { en: '' },
  },
});

mode: 'always' normally means every URL carries its locale (/de/team, /ja/quiz). The prefixes: { en: '' } line carves out an exception: English gets no prefix, so it sits at /team and /quiz while everything else keeps its language code.
Why bother? Two reasons. English is the primary audience, so clean URLs there are worth a bit of extra config. And it keeps one canonical URL per page instead of two (/team and /en/team) pointing at the same content, which is exactly the kind of thing that makes Google treat your pages as duplicates.

Wiring the locale into prerendering

next-intl normally detects the locale in middleware. With static export, middleware never runs — the host just serves files. So the locale has to be plumbed through the route segment manually:

// src/i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { routing } from './routing';
export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;
  if (!locale || !routing.locales.includes(locale)) {
    locale = routing.defaultLocale;
  }
  return {
    locale,
    timeZone: 'UTC',
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

The requestLocale here comes from the [locale] directory in the app router, not from a header. Messages live as plain JSON per language under src/messages/, loaded statically at build time. No dynamic import at runtime, no bundling surprises.
There's one critical piece that's easy to miss: you have to tell Next.js which locale paths to prerender. That's what generateStaticParams does, in the root layout under app/[locale]/layout.tsx:

// src/app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';
export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

This ensures every language gets its own folder of static HTML files at build time. Miss it, and you only get the default locale.
Then every server component calls setRequestLocale(locale) so the page's metadata and content both know which language they're rendering. Miss that call and you get a build error, which is honestly a feature — it means the locale is never silently wrong.

The SEO-critical part: hreflang

Eight near-identical pages per feature means Google needs help knowing they're translations of each other, not duplicates. That's what hreflang is for, and getting it right was the main reason I put real effort into this.

// src/lib/seo.ts
const DOMAIN = 'https://pokemongen.com';
const LOCALES = ['en', 'de', 'ja', 'ko', 'es', 'fr', 'pt', 'it'];
export function alternates(path: string, locale: string) {
  const cleanPath = path === '/' ? '' : path;
  const canonical =
    locale === 'en' ? `${DOMAIN}${cleanPath}` : `${DOMAIN}/${locale}${cleanPath}`;
  return {
    canonical,
    languages: {
      ...Object.fromEntries(
        LOCALES.map((l) => [l, l === 'en' ? `${DOMAIN}${cleanPath}` : `${DOMAIN}/${l}${cleanPath}`])
      ),
      'x-default': `${DOMAIN}${cleanPath}`,
    },
  };
}

This feeds into Next's alternates metadata field, so every prerendered page ends up with a canonical tag plus an <link rel="alternate" hreflang="..."> for each of the eight languages, and an x-default pointing at the English URL.
x-default is the one people skip. It's what you want a user with no matching language (or a crawler) to land on. I point it at English. If you forget it, Google has to guess, and it guesses wrong often enough that it's worth the extra line.
The other half of the problem is that metadata has to be translated too, not just the page body. Title, description, and OpenGraph tags are all strings in the same JSON files, pulled per locale. Here's a helper that ties it all together:

// src/lib/page-helpers.tsx
import { getTranslations, setRequestLocale } from 'next-intl/server';
import { alternates } from '@/lib/seo';
export function makePageMetadata({ namespace, path }: { namespace: string; path: string }) {
  return async function generateMetadata(locale: string) {
    setRequestLocale(locale);
    const t = await getTranslations({ locale, namespace });
    return {
      title: t('title'),
      description: t('description'),
      alternates: alternates(path, locale),
      openGraph: { title: t('title'), description: t('description') },
    };
  };
}

And here's how you use it in a page:

// src/app/[locale]/page.tsx
import { makePageMetadata } from '@/lib/page-helpers';
export async function generateMetadata({ params }: { params: { locale: string } }) {
  return makePageMetadata({ namespace: 'home', path: '/' })(params.locale);
}

A page whose H1 says "Team Builder" in German but whose title tag still says "Team Builder" in English is a common i18n bug. Keeping both in the same message namespace means they either both translate or neither does.

Trade-offs of static export

The tradeoffs are real, and they were all fine for this project but worth listing:

No next/image optimization. Already mentioned — flag off, serve plain PNGs.
No runtime redirects or rewrites. If I wanted /pt to redirect somewhere, it'd have to be a Cloudflare Pages rule, not Next config.
Every locale is physical files. Eight languages times however many routes means the build emits a lot of HTML. Fast to serve, but a 9th language is a decision, not a one-line config change.
Not-found pages need a locale too. A 404 is still a page, so it lives under [locale] and the static export maps the default one to 404.html for the host. The build itself is a small Node script: run next build, then walk the prerendered HTML and lay it out as /<locale>/<page>/index.html the way Cloudflare Pages expects, mapping _not-found.html to 404.html. It's the kind of glue that takes twenty minutes to write and saves you from fighting an adapter later. ## Was it worth it? For a static, content-focused tool site, yes. The pages load instantly, hosting is effectively free, and the hreflang setup means search engines actually surface the right language to the right region instead of ranking eight copies against each other. The honest downside is the translations. Eight JSON files maintained by hand is tedious, and if your content changes weekly this approach will make you hate yourself. It works here because the copy is mostly static. If your site is heavy on server-side features or user accounts, you'd reach for a server and middleware-based locale detection instead — this setup only wins when you can afford to be fully static. You can try the live site at pokemongen.com.