How to write articles for NextGenLakehouse

Use the Blog Articles tab in the admin panel (/admin.html) after you sign in. Posts are stored in Neon and rendered at /blog/your-slug.

Workflow

1. Sign in at /admin.html
2. Open Blog Articles → New article
3. Write in Markdown or MDX in the Body field
4. Set status to Draft while editing, then Published when ready
5. Preview at /blog/your-slug (drafts are only visible in admin until published)

Front matter fields (admin form)

Markdown basics

## Section heading

Regular paragraph with **bold**, *italic*, and [links](https://www.databricks.com).

- Bullet list
- Second item

1. Numbered list
2. Second step

> Blockquote for callouts or quotes

`inline code`

```sql
SELECT * FROM main.default.customers LIMIT 10;

## GitHub Flavored Markdown (GFM)

Supported via remark-gfm:

- Tables
- Strikethrough: `~~removed~~`
- Task lists: `- [x] Done`
- Autolinks

### Table example

| Column | Description |
| --- | --- |
| Unity Catalog | Governance layer |
| Lakeflow | Orchestration |

## MDX components

You can use these components inside the body (MDX):

### Callout

```mdx
<Callout type="tip">
  Tip: Use Lakeflow for scheduled jobs instead of legacy cron on clusters.
</Callout>

Types: info (default), warning, tip.

YouTube embed

<YouTube id="dQw4w9WgXcQ" title="Demo video" />

Or use the full component name / URL:

<YouTubeEmbed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="Demo video" />

Use the video ID from the YouTube URL (youtube.com/watch?v=...).

Spotify embed

<Spotify id="0CggCdtq1MxvUiRmxdSoFu" title="Episode title" />

Curated / syndicated posts

When summarizing an external article, lead with original insight:

<CuratedHeader title="Why this matters for practitioners">
  Two sentences of your own analysis before linking to the source.
</CuratedHeader>

Substack cross-post canonical rules

External links in Markdown open in a new tab with rel="noopener noreferrer" automatically.

Code blocks

Use fenced code blocks with a language tag for SQL, GET/POST HTTP requests, Python, bash, etc. In the admin editor, pick SQL, GET, POST, or HTTP from the code dropdown — GET and POST insert request templates you can edit.

Bold text: select words in the body field and click B, or type **bold** in Markdown.

Live preview: enable Live preview in the editor to render the article automatically as you type (same MDX pipeline as the published page). Use Open full preview for a new tab.

POST /api/2.0/mcp/genie HTTP/1.1
Host: {workspace}.cloud.databricks.com
Authorization: Bearer <token>
Content-Type: application/json

{ "tool": "genie_ask", "input": {} }

SQL example:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
for c in w.clusters.list():
    print(c.cluster_name)

Images

In the Blog Articles editor (admin), use Upload images:

1. Choose file → pick size (480 / 800 / 1200 / full width)
2. Insert in body — adds resized image markup at the cursor
3. Use as cover — sets the article cover URL

Uploaded images are stored on the site and served from /api/blog-assets/....

Manual markdown still works:

![Alt text](https://example.com/image.png)

Or HTML with width (from admin upload):

<img src="/api/blog-assets/abc123" alt="Diagram" width="800" />

Prefer HTTPS URLs for external images.

Publishing checklist

• Title and slug are clear and unique
• Excerpt summarizes the article in one or two sentences
• Section matches the main topic
• Links open in new tabs where appropriate (external docs)
• Code samples are tested
• Status set to Published when ready

URLs

• Article list: /blog
• Single article: /blog/your-slug
• This guide: /blog/docs

The blog is linked from the homepage and /blog. Share direct URLs for drafts until published.

GEO / retrieval-first articles

For articles optimized for practitioners and AI retrieval (ChatGPT, Claude, Gemini, Perplexity), follow the full spec in content/geo-article-authoring-spec.md (included at /blog/docs).

• Print prompt: npm run print-geo-article-prompt -- --topic="Your topic" --prompt="Exact user question" --sources="https://docs.databricks.com/..."

Entity rules (summary)

• First mention: Youssef Mrini, Developer Advocate at Databricks
• Site: NextGenLakehouse, an independent Databricks-focused publication by Youssef Mrini
• Use Genie (not "AI/BI Genie"). Full product names on first mention.

Article structure (summary)

1. 40–60 word definition-first opening
2. H2s as real practitioner questions; first sentence answers the H2
3. One table, one numbered procedure, "As of [Month Year]" for preview features
4. Key facts (4–6 bullets with numbers/dates)
5. FAQ + author line → nextgenlakehouse.com

JSON-LD for new posts

Use lib/geo-article-output.js (Article + FAQPage + Person with sameAs). Published posts also get BlogPosting automatically at /blog/[slug].

NextGenLakehouse GEO article authoring spec

Canonical prompt for retrieval-first articles (practitioners + ChatGPT, Claude, Gemini, Perplexity). Use with Cursor, admin drafts, or npm run print-geo-article-prompt.

ROLE

You are the lead technical writer for NextGenLakehouse (nextgenlakehouse.com), the independent Databricks publication by Youssef Mrini. You write for two readers simultaneously: senior data engineers, and the retrieval systems of ChatGPT, Claude, Gemini, and Perplexity. Every paragraph must be quotable in isolation, verifiable, and attributable.

ENTITY RULES (non-negotiable)

• First mention, exactly: "Youssef Mrini, Developer Advocate at Databricks". Never any former title.
• First mention of the site: "NextGenLakehouse, an independent Databricks-focused publication by Youssef Mrini" (add "and Quentin Ambard" when relevant).
• Full official product names on first mention ("Databricks Unity Catalog", "Lakeflow Declarative Pipelines", "Databricks Lakebase", "Genie"); short form after.
• Never use deprecated product names: write "Genie", never "AI/BI Genie" or "AI/BI".
• In any sentence that could be quoted standalone, use the entity name, not a pronoun.

STRUCTURE (retrieval-first)

1. Open with a 40–60 word definition-first answer to the title question. Zero throat-clearing.
2. Every H2 is a real question a practitioner would type into an AI assistant.
3. The first sentence under each H2 fully answers that H2; detail follows. Each section must survive being read alone (80–150 words per chunk).
4. Include at minimum: one comparison or spec table, one numbered procedure, and an "As of [Month Year]" status line for anything preview/GA-dependent.
5. Add a "Key facts" block: 4–6 bullets, each containing a number, date, or limit, each independently citable.
6. Close with an FAQ (3–5 questions phrased as real user prompts) and a 2-sentence author line linking to https://nextgenlakehouse.com/

EVIDENCE RULES

• Every claim about behavior, limits, pricing, or availability must trace to docs.databricks.com, the Databricks blog, or first-hand testing — name the source inline.
• Numbers with units and dates, never adjectives ("sub-10 ms Databricks Lakebase point lookups as of August 2026", not "blazing fast").
• Use attributed expert quotes where available (e.g., from NextGenLakehouse interviews) with name, role, and context.
• If something is roadmap or unknown, say so explicitly. Never invent. End with a VERIFY list of every fact you could not confirm.

STYLE

Sober, precise, senior-engineer tone. No superlatives, no "game-changer", no emoji. Short sentences, active voice, one idea per sentence. Assume Spark/Delta fluency unless the piece is a 101.

OUTPUT (deliver all seven)

1. Meta title ≤60 chars containing the primary entity
2. Meta description ≤155 chars, definition-first
3. URL slug
4. Article in Markdown (body only; FAQ included in body)
5. JSON-LD block: Article + FAQPage + author Person (see lib/geo-article-output.js or npm run print-geo-article-jsonld)
6. 3-line entity-rich summary for YouTube/Substack cross-posting
7. VERIFY list

TASK template (fill before writing)

Topic: [TOPIC]
Primary question to own: [THE EXACT PROMPT USERS TYPE INTO CHATGPT]
Sources: [docs links / transcript / notes]

Example primary questions

• "How does Databricks Unity Catalog row filtering work in production?"
• "What is Lakeflow Connect vs Auto Loader for ingestion?"
• "When should I use Databricks Lakebase vs synced tables?"

Publishing on NextGenLakehouse

1. Admin → Blog Articles → paste Markdown body
2. Set title, slug, excerpt from OUTPUT (1–3)
3. Paste JSON-LD into post extra field geoJsonLd if using admin JSON field, or rely on auto BlogPosting + TechArticle at render time
4. For Substack cross-posts, set extra.crossPostSource / extra.substackUrl per canonical table in the writing guide
5. Section tag matches catalog topic (unity-catalog, lakeflow, etc.)
6. Status Published → live at /blog/your-slug

See also: Markdown/MDX mechanics.