Skip to content

readme.md

Latest commit

 

History

History
222 lines (150 loc) · 9.05 KB

readme.md

File metadata and controls

222 lines (150 loc) · 9.05 KB
Raw

DocumentDB Website

A modern website for DocumentDB built with Next.js for the main site and Jekyll for the Announcements (/announcements/) and Blogs (/blogs/) sections. The site features project news, community blog posts, and technical documentation, with documentation content automatically pulled from the documentdb/docs repository during the build process.

LLM Access and Discovery

public/llms.txt is published at /llms.txt by the Next.js static export. It welcomes LLMs and AI assistants to access all public site content and provides links to documentation, Announcements, Blogs, the sitemap, and source repositories. Keep these links current when site sections change.

This is a discovery guide, not an access-control mechanism or a replacement for existing content licenses and website terms. public/robots.txt already allows all crawlers.

Prerequisites for Development

  • Node.js (20 or higher)

  • Ruby with Bundler (for the Jekyll-powered content sections)

  • 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:

    npm install

  3. Install Ruby dependencies:

    bundle install

  4. Start the Next.js development server:

    npm run dev

  5. For a full static preview, including Announcements and Blogs:

    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 Announcements and Blog Posts

Announcements and blog posts are managed locally in this repository. Contribute directly through a pull request to this repository.

Choose a section by topic, regardless of where the article is hosted:

  • announcements: project news, launches, releases, and community milestones.
  • blogs: explainers, tutorials, technical deep dives, and community perspectives.

Release announcement posts should specify section: announcements; the featured and release_post flags continue to control card emphasis.

The two navigation tabs link to separate static HTML pages, so readers and crawlers can follow their links without JavaScript. Existing local article URLs remain under /blogs/posts/, and /blogs/feed.xml continues to include all local posts from both sections for existing subscribers.

The listing pages live in the top-level announcements/ and blogs/ directories. Both share the templates, post metadata, and articles under blogs/. npm run build:blogs builds both directories in a temporary Jekyll site and publishes only out/announcements/ and out/blogs/, preserving the rest of the Next.js export. Set NEXT_BASE_PATH=/preview for a prefixed deployment; the existing JEKYLL_BASE_PATH=/preview/blogs setting is also supported when NEXT_BASE_PATH is unset.

You can publish 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
section: blogs
cover_image: /blogs/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 includes it only in the selected section, using the same card layout for both sections. Local posts default to section: blogs when it is omitted; set section: announcements for news. category identifies the publication and controls the card styling, not the section. Images can be referenced directly from Markdown, for example:

    ![Architecture diagram]({{ '/blogs/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. Every external entry must specify section: announcements or section: blogs.

  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.

Important

Please refer to that repository for instructions on contributing:

  • Documentation articles (getting-started/, postgres-api/, architecture/, etc.)
  • API reference content (api-reference/)

Testing the Deployment Workflow in a Fork

The deployment workflow builds the static site, mirrors the DocumentDB release packages into APT and YUM repositories, signs those repositories, and publishes everything to GitHub Pages.

Only the static site build is mandatory. Packaging and signing are resolved automatically at the start of the run, so a fork with no repository secrets can exercise the whole workflow:

  1. Enable GitHub Pages in your fork (Settings > Pages > Source: GitHub Actions)

  2. Push to main in your fork, or run the workflow manually from the Actions tab

  3. Check the run summary, which reports which optional features were enabled and why

The two optional halves are controlled independently:

Setting Type Default Effect when enabled
BUILD_PACKAGES Variable On in documentdb/documentdb.github.io, off in forks Downloads the release .deb and .rpm assets and builds the APT and YUM repositories
GPG_PRIVATE_KEY Secret unset Signs the APT Release file and the RPM metadata, and publishes documentdb-archive-keyring.gpg
DOCUMENTDB_VERSION Variable latest Release tag the packages are mirrored from

Set BUILD_PACKAGES to true in your fork if you specifically want to test the packaging path; signing is then skipped unless you also add your own GPG_PRIVATE_KEY.

Important

Signing is optional, but it never fails quietly. When GPG_PRIVATE_KEY is set, the run fails if the key cannot be imported or the signatures are not produced. Publishing an unsigned repository over a signed one breaks apt-get update for every client that already trusts the keyring.

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:

Open in GitHub Codespaces

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.