DocumentDB Website

A modern website for DocumentDB built with Next.js for the main site and Jekyll for the /blogs/ section. The site features community blog posts and technical documentation, with content automatically pulled from the documentdb/docs repository during the build process.

Prerequisites for Development

• Node.js (20 or higher)

• Ruby with Bundler (for the Jekyll-powered blog section)

• Git (for cloning documentation content)

You can develop locally on any machine with these prerequisites installed, or use GitHub Codespaces for a pre-configured environment.

Getting Started

Get started by cloning and running this repository locally.

1. Clone this repository

2. Install dependencies:

3. Install Ruby dependencies:

4. Start the Next.js development server:

5. For a full static preview, including the Jekyll-powered blog section:

   npm run build
   npm run start

6. Observe that the preview site will be available at http://localhost:3000

The first time you run npm run dev or npm run build, documentation content will be automatically compiled from the documentdb/docs repository.

Contributing

We welcome contributions to improve the DocumentDB website, whether it's blog posts, bug fixes, or enhancements to the site itself.

Contributing Blog Posts

Blog posts are managed locally in this repository. Contribute directly through a pull request to this repository.

You can publish blog content in two ways:

1. Markdown posts hosted in this repo

   Add a new file under blogs/_posts/ using the Jekyll naming format:

   blogs/_posts/YYYY-MM-DD-my-post-title.md
   

   Start it with front matter like:

   ---
   title: My Blog Post
   description: One-line summary used in the blog card.
   date: 2026-03-19
   featured: false
   author: Your Name
   category: documentdb-blog
   cover_image: /assets/images/posts/my-post-title/hero.png
   cover_image_alt: Short description of the image
   tags:
     - Example
     - Markdown
   ---

   Store post images under:

   blogs/assets/images/posts/my-post-title/
   

   Then write the post body in Markdown. Jekyll renders the post page and uses the same card layout on the blog index. Images can be referenced directly from Markdown, for example:

   ![Architecture diagram]({{ '/assets/images/posts/my-post-title/diagram.png' | relative_url }})

2. Curated external articles

   Open blogs/_data/posts.yml and add a new entry following the existing YAML format when you want the card to link to an article hosted elsewhere.

3. Submit a pull request for review

Contributing Documentation & Reference Content

Documentation articles and API reference content are managed in a separate repository. For more information, see documentdb/docs.

Content Configuration

Documentation content is automatically compiled during builds from external repositories. The mapping is configured in content.config.json.

{
  "sources": [
    {
      "repository": "https://github.com/documentdb/docs",
      "branch": "main",
      "mappings": [
        {
          "source": "api-reference",
          "target": "reference"
        },
        {
          "source": "getting-started",
          "target": "articles/getting-started"
        }
      ]
    }
  ],
  "include": ["**/*.md", "**/*.yml"],
  "exclude": ["**/{readme,README}.md"]
}

Configuration options

The content.config.json file controls how documentation is compiled from external sources into this site.

• sources - Array of repositories to clone content from. Each source includes:
  • repository - Git repository URL
  • branch - Git branch to clone from
  • mappings - Array of source folder to target folder mappings
• include - Array of glob patterns for files to include (opt-in filtering)
• exclude - Array of glob patterns for files to exclude

Manual content operations

While content is automatically compiled during builds, you can manually trigger these operations during development:

# Build the full static site artifact
npm run build

# Start the static preview server
npm run start

Develop in GitHub Codespaces

Launch a pre-configured development environment with all dependencies installed:

The Codespaces environment includes:

• Node.js 20
• Git
• Visual Studio Code extensions for Markdown and YAML editing
• All npm dependencies

Simply run npm run dev after the container starts.