Skip to content

Refine getting-started install primer #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abinav2307 merged 2 commits into from
Apr 13, 2026
Merged

Refine getting-started install primer #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c340021
fix page
guanzhousongmicrosoft Apr 10, 2026
fa4ce5e
Refine getting-started install primer
guanzhousongmicrosoft Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions app/components/Markdown.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,25 +90,25 @@ function getMarkdownComponents() {
</h4>
),

// Unordered lists with blue round bullets
ul: ({ depth, ...props }: any) => (
// Unordered lists with consistent nested indentation
ul: ({ ...props }: any) => (
<ul
className={depth > 0 ? "ml-6 space-y-2 text-gray-300 mb-4 list-disc list-inside" : "space-y-2 text-gray-300 mb-4 list-disc list-inside"}
className="mb-4 list-disc space-y-2 pl-6 text-gray-300 [&_ul]:mb-0 [&_ul]:mt-2 [&_ul]:list-[circle] [&_ul]:pl-6 [&_ol]:mb-0 [&_ol]:mt-2 [&_ol]:pl-6"
{...props}
/>
),

// Ordered lists with blue numbers
// Ordered lists with consistent nested indentation
ol: ({ ...props }) => (
<ol
className="space-y-2 text-gray-300 mb-4 list-decimal list-inside"
className="mb-4 list-decimal space-y-2 pl-6 text-gray-300 [&_ul]:mb-0 [&_ul]:mt-2 [&_ul]:pl-6 [&_ol]:mb-0 [&_ol]:mt-2 [&_ol]:pl-6"
{...props}
/>
),

// List items
li: ({ ...props }) => (
<li className="marker:text-blue-400 marker:mr-3 marker:flex-shrink-0 [&>p]:m-0 [&>p]:inline" {...props} />
<li className="leading-relaxed marker:text-blue-400 [&>p]:m-0 [&>p]:inline [&>ul]:mb-0 [&>ul]:mt-2 [&>ol]:mb-0 [&>ol]:mt-2" {...props} />
),

// Inline code
Expand Down
14 changes: 12 additions & 2 deletions app/data/samples.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,16 @@
import { Sample } from '../types/Sample';

export const samples: Sample[] = [
{
id: 'personal-memory-mcp-ts',
title: 'Personal AI Memory: Cross-Platform MCP Server with DocumentDB Vector Search',
description: 'A TypeScript MCP server that gives any AI assistant — Copilot CLI, Claude, Gemini — persistent personalized memory backed by DocumentDB. Uses a 4-layer retrieval strategy: cosmosSearch vector similarity, full-text search indexes, array tag queries, and regex fallback. Demonstrates DocumentDB\'s vector search (pgvector), MongoDB wire protocol compatibility, text indexes, atomic update operators, and flexible document schema in a practical AI application.',
language: 'TypeScript',
industry: 'AI/ML',
difficulty: 'Intermediate',
tags: ['MCP', 'AI Memory', 'Vector Search', 'Full-Text Search', 'Text Index', 'Express', 'RAG', 'DocumentDB OSS', 'Open Source'],
githubUrl: 'https://github.com/documentdb/documentdb-samples-gallery/tree/main/personal-memory-mcp-ts',
},
{
id: 'hotel-agent-ts',
title: 'Hotel Recommendation Agent: RAG with Native Vector Search and LLM Synthesizer in TypeScript',
Expand Down Expand Up @@ -66,11 +76,11 @@ export const samples: Sample[] = [
{
id: 'activity-log-fastapi-py',
title: 'Activity Log & Notification Service: Real-Time Event Ingestion with FastAPI, Beanie, and DocumentDB',
description: 'A production-style async Python backend that ingests high-volume activity events via FastAPI, stores them in DocumentDB using the Beanie ODM over Motor, and exposes endpoints to query recent activities, compute server-side aggregation statistics ($facet pipeline), and stream real-time ERROR alerts to clients over WebSockets.',
description: 'A production-style async Python backend that ingests high-volume activity events via FastAPI, stores them in DocumentDB using the Beanie ODM (backed by PyMongo async), and exposes endpoints to query recent activities, compute server-side aggregation statistics ($facet pipeline), and stream real-time ERROR alerts to clients over WebSockets.',
language: 'Python',
industry: 'DevOps / Observability',
difficulty: 'Intermediate',
tags: ['FastAPI', 'Beanie', 'Motor', 'REST API', 'WebSocket', 'Aggregation', 'DocumentDB OSS', 'Open Source'],
tags: ['FastAPI', 'Beanie', 'PyMongo', 'REST API', 'WebSocket', 'Aggregation', 'DocumentDB OSS', 'Open Source'],
githubUrl: 'https://github.com/documentdb/documentdb-samples-gallery/tree/main/activity-log-fastapi-py',
}
];
160 changes: 127 additions & 33 deletions app/docs/[section]/[[...slug]]/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ const dockerQuickRunCommand = `docker run -dt --name documentdb \\
--username <YOUR_USERNAME> \\
--password <YOUR_PASSWORD>`;

const primerPrimaryLinkClass =
"inline-flex w-full items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400 sm:w-auto";

const primerSecondaryLinkClass =
"font-semibold text-blue-300 transition-colors hover:text-blue-200";

export async function generateStaticParams() {
const paths = getAllArticlePaths();

Expand Down Expand Up @@ -50,11 +56,16 @@ export async function generateMetadata({ params }: PageProps) {

export default async function ArticlePage({ params }: PageProps) {
const { section, slug = [] } = await params;
const currentSlug = slug[slug.length - 1];

if (section === 'getting-started' && slug[slug.length - 1] === 'prebuilt-packages') {
if (section === 'getting-started' && currentSlug === 'prebuilt-packages') {
redirect('/docs/getting-started/packages');
}

if (section === 'getting-started' && currentSlug === 'vscode-extension-guide') {
redirect('/docs/getting-started/vscode-quickstart');
}

const articleData = getArticleByPath(section, slug);

if (!articleData) {
Expand Down Expand Up @@ -152,40 +163,123 @@ export default async function ArticlePage({ params }: PageProps) {
{frontmatter.layout === 'coming-soon' && <ComingSoon />}

{showInstallPrimer && (
<section className="mb-8 rounded-xl border border-blue-500/30 bg-blue-500/5 p-5">
<h2 className="text-xl font-semibold text-white">Install DocumentDB first</h2>
<p className="mt-2 text-sm text-gray-300">
Start with Docker for the fastest setup, or choose Linux packages for persistent servers.
<section className="mb-8 rounded-2xl border border-blue-500/30 bg-gradient-to-br from-blue-500/10 via-neutral-900/90 to-neutral-900/90 p-6">
<p className="text-xs font-semibold uppercase tracking-[0.18em] text-blue-200">
Recommended flow
</p>
<h2 className="mt-2 text-2xl font-semibold text-white">
Install and verify DocumentDB
</h2>
<p className="mt-2 max-w-3xl text-sm leading-6 text-gray-300">
Choose one install path first. After DocumentDB is running, verify the
connection with mongosh before moving to a driver quick start.
</p>
<div className="mt-4 grid gap-4 lg:grid-cols-2">
<div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
<p className="mb-3 text-sm font-semibold text-white">Quick run with Docker</p>
<CommandSnippet command={dockerQuickRunCommand} label="Docker" />
<div className="mt-5 rounded-xl border border-neutral-800 bg-neutral-950/40 p-4">
<div className="mb-4 flex items-start gap-3">
<span className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-blue-400/30 bg-blue-500/10 text-xs font-semibold text-blue-200">
1
</span>
<div>
<p className="text-sm font-semibold text-white">
Choose an install path
</p>
<p className="mt-1 text-sm text-gray-400">
Use Docker for the fastest local setup, or Linux packages for a
persistent host installation.
</p>
</div>
</div>
<div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
<p className="text-sm font-semibold text-white">Install from Linux packages</p>
<p className="mt-2 text-sm text-gray-400">
Use the package finder to generate the exact apt/rpm command for your distro, architecture, and PostgreSQL version.
</p>
<div className="mt-4 flex flex-wrap gap-3">
<Link
href="/docs/getting-started/docker"
className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
>
Docker guide
</Link>
<Link
href="/packages"
className="inline-flex items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400"
>
Open package finder
</Link>
<Link
href="/docs/getting-started/packages"
className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
>
Linux packages docs
</Link>
<div className="grid gap-4 lg:grid-cols-2">
<div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
<p className="text-sm font-semibold text-white">
Run locally with Docker
</p>
<p className="mt-2 text-sm text-gray-400">
Best for evaluation, local development, and quick testing.
</p>
<div className="mt-4">
<CommandSnippet command={dockerQuickRunCommand} label="Docker" />
</div>
<div className="mt-4">
<Link
href="/docs/getting-started/docker"
className={primerPrimaryLinkClass}
>
Docker Quick Start
</Link>
</div>
</div>
<div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
<p className="text-sm font-semibold text-white">
Install from Linux packages
</p>
<p className="mt-2 text-sm text-gray-400">
Use the repository-backed package flow when you want a persistent
server install. Generate the exact apt or rpm command with the{" "}
<Link href="/packages" className={primerSecondaryLinkClass}>
Package Finder
</Link>
.
</p>
<div className="mt-4">
<Link
href="/docs/getting-started/packages"
className={primerPrimaryLinkClass}
>
Linux Packages Quick Start
</Link>
</div>
</div>
</div>
</div>
<div className="mt-4 rounded-xl border border-neutral-800 bg-neutral-950/40 p-4">
<div className="flex items-start gap-3">
<span className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-blue-400/30 bg-blue-500/10 text-xs font-semibold text-blue-200">
2
</span>
<div className="min-w-0">
<p className="text-sm font-semibold text-white">
Recommended: verify with mongosh
</p>
<p className="mt-1 text-sm text-gray-400">
This is the fastest shared validation path after either install
option because it confirms authentication, TLS, and a working
endpoint before you add editor or driver setup. If you already
know your target workflow, you can skip this and continue directly
with VS Code or a driver quick start.
</p>
<div className="mt-4 flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:gap-4">
<Link
href="/docs/getting-started/mongo-shell-quickstart"
className={primerPrimaryLinkClass}
>
Mongo Shell Quick Start
</Link>
<p className="text-sm text-gray-400">
Or go directly to{" "}
<Link
href="/docs/getting-started/vscode-quickstart"
className={primerSecondaryLinkClass}
>
Visual Studio Code Quick Start
</Link>
,{" "}
<Link
href="/docs/getting-started/nodejs-setup"
className={primerSecondaryLinkClass}
>
Node.js Quick Start
</Link>{" "}
or{" "}
<Link
href="/docs/getting-started/python-setup"
className={primerSecondaryLinkClass}
>
Python Quick Start
</Link>
.
</p>
</div>
</div>
</div>
</div>
Expand Down
4 changes: 2 additions & 2 deletions app/lib/packageInstall.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] https://apt.postgresql.
curl -fsSL https://documentdb.io/documentdb-archive-keyring.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/documentdb-archive-keyring.gpg && \\
echo "deb [arch=${aptArch} signed-by=/usr/share/keyrings/documentdb-archive-keyring.gpg] https://documentdb.io/deb stable ${aptTarget}" | sudo tee /etc/apt/sources.list.d/documentdb.list >/dev/null && \\
sudo apt update && \\
sudo apt install -y postgresql-${aptPgVersion}-documentdb`;
sudo apt install -y postgresql-${aptPgVersion}-documentdb documentdb_gateway`;
}

export function buildRpmInstallCommand(
Expand All @@ -78,5 +78,5 @@ printf '%s\\n' \\
'enabled=1' \\
'gpgcheck=1' \\
'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg' | sudo tee /etc/yum.repos.d/documentdb.repo >/dev/null && \\
sudo dnf install -y postgresql${rpmPgVersion}-documentdb`;
sudo dnf install -y postgresql${rpmPgVersion}-documentdb documentdb-gateway`;
}
Loading