From 3770dd7e211a6132889f53f29aa7ab043b99c4b6 Mon Sep 17 00:00:00 2001 From: Alex Le Date: Fri, 20 Mar 2026 14:53:02 -0700 Subject: [PATCH 1/8] initial update Signed-off-by: Alex Le --- .github/pull_request_template.md | 35 +++------------ CONTRIBUTING.md | 13 ++++++ README.md | 76 ++++++++++++++++++++++---------- 3 files changed, 72 insertions(+), 52 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2777a0c1..eb17c8ca 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,47 +1,24 @@ ### Summary ### Issue link -This Pull Request is linked to issue (URL): [REPLACE ME] - -### Content Changes - - - -### Implementation - -### Testing +### Content Changes - -### Checklist - -Before submitting the PR make sure the following are checked: - -- [ ] This Pull Request is related to one issue. -- [ ] Commit message has a detailed description of what changed and why. -- [ ] All commits are signed off with `--signoff` flag. -- [ ] `pnpm build` runs successfully. -- [ ] Links have been checked for validity. -- [ ] Destination branch is correct - main or release -- [ ] Create merge commit if merging release branch into main, squash otherwise. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1eabd769 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Contributing to Valkey GLIDE Documentation + +Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! This guide will go over how to contribute to our documentations. + +> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, see the [valkey-glide CONTRIBUTING guide](https://github.com/valkey-io/valkey-glide/). + +## Prerequisites + +Please ensure that you have set up the project according to our [Readme](/README.md). + +## Content Guidelines + +talk about diataxis... \ No newline at end of file diff --git a/README.md b/README.md index 84261571..60a652c8 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,66 @@ # Valkey GLIDE Documentation -This repository host the source for the Valkey GLIDE documentation [site](https://glide.valkey.io). +Welcome to the Valkey GLIDE documentation repository. The site is available at https://glide.valkey.io. -## Technology +> **Note:** This repository contains only the documentation of Valkey GLIDE. +> To contribute to the Valkey GLIDE client library itself, visit [valkey-glide](https://github.com/valkey-io/valkey-glide/). + +## Overview The site is built with [Starlight](https://starlight.astro.build/), an Astro framework for building static documentation sites. -The framework provides out-of-the-box features for building documentations like components, site search, navigation, and integrations with MDX files. It also leverages Astro's features like island architecture to build dynamic components. +The framework provides out-of-the-box features for building documentations like UI components, site search, navigation, all using a Markdown like syntax. It also leverages Astro's features to build custom dynamic components. +This aims to allow contributors to quickly add or edit existing pages using familiar Markdown syntax, while having the options to extend the site with modern Javascript components. ## Getting Started -First clone the repo and install the required tools. - -```bash -git clone git@github.com:valkey-io/valkey-glide-docs.git +You'll need the following installed: -# npm is fine too. -brew install pnpm -``` +- [Node.js](https://nodejs.org/) v20+ +- [pnpm](https://pnpm.io/) v10+ (`brew install pnpm` or `npm install -g pnpm`) -Then install the dependencies +Then clone the repo and install dependencies: ```bash +git clone git@github.com:valkey-io/valkey-glide-docs.git cd ./valkey-glide-docs pnpm install ``` For development, run `pnpm dev`. It will spin up a hot-loading development server to serve the documentation pages. -### Link Checker +### Making Changes + +Page content lives under `src/content/docs/` as `.mdx` files. + +- **Edit a page:** Modify the corresponding `.mdx` file. +- **Add a new page:** Create a new `.mdx` file under `src/content/docs/`. Every file requires frontmatter: + + ```mdx + --- + title: Your page title + --- + + Your content follows... + ``` + +- **Update the sidebar navigation:** Add your new page to `astro.config.mjs`. + +For a guidelines on how to write new articles, take a look at our [Contributing](/CONTRIBUTING.md) page. + +## Commit Requirements + +All commits must include the `--signoff` flag to certify the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). + +## Making a Pull Request + +Before making a pull request, make sure that you have a corresponding issue created either in this repo or the main Valkey GLIDE source repo. Each pull request should be related to an issue, unless it is a minor fix. + +When making a pull request, please make sure to follow our template and complete the required sections. + +Importantly, ensure that your PR ha + +## Link Checker We use [lychee](https://github.com/lycheeverse/lychee) to check for broken links. Configuration rules (exclusions) are defined in our `lychee.toml`. @@ -44,20 +76,18 @@ Then to run the build and check links: pnpm build:check-links ``` -## Making Content Changes - -In general, page contents are located under `src/content/docs`. +## Code Style & Formatting -- For simple content update, change the appropriate `.mdx` files in the folder structure. -- To create a new page, add a new `.mdx` file under `src/content/docs`. -- To change the navigation sidebar, update `astro.config.mjs`. +The project uses [Prettier](https://prettier.io/) for general formatting and [remark](https://github.com/remarkjs/remark) for MDX/Markdown linting. Configuration is in `.prettierrc.json` and `.remarkrc.json`. -Note that all `.mdx` files requires a frontmatter. +Run formatting before submitting a PR: +```bash +pnpm format ``` ---- -title: Your page title. ---- -Your contents follows ... +To check formatting without modifying files: + +```bash +pnpm format:check ``` From f7e64f2ca93758838bf16aa95294a1b4c5d33298 Mon Sep 17 00:00:00 2001 From: Alex Le Date: Thu, 9 Apr 2026 15:02:47 -0700 Subject: [PATCH 2/8] added contribution doc Signed-off-by: Alex Le --- .github/pull_request_template.md | 5 ++++- CONTRIBUTING.md | 27 +++++++++++++++++++++------ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index eb17c8ca..b24b0494 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,10 @@ Required. Summarize your changes in a short paragraph. ### Issue link diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1eabd769..3dd1a5d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,28 @@ # Contributing to Valkey GLIDE Documentation -Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! This guide will go over how to contribute to our documentations. +Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! -> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, see the [valkey-glide CONTRIBUTING guide](https://github.com/valkey-io/valkey-glide/). +This guide aims to help answer more conceptual questions about writing documentations like: +- What kind of documentation should I write? +- How should I write my documentations? -## Prerequisites +For more technical instructions, like how to set up the environment, see our [Readme](/README.md). -Please ensure that you have set up the project according to our [Readme](/README.md). +> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, visit the [valkey-glide repository](https://github.com/valkey-io/valkey-glide/). -## Content Guidelines +## Language Agnostic Documentation -talk about diataxis... \ No newline at end of file +The goal of Valkey GLIDE documentations is to be the single source of truth for the various Valkey GLIDE clients. + +When writing documentations, it should be written in considerations for all client languages. In practice, this is easier than it sounds due to the Rust core design. Because clients share the same core we expects them to behave similarly; They naturally are able share the same documentation with language specific examples included when appropriate. Often these comes as code examples. + +## Adding Documentation For A New Feature. + +Users reach for the documentation because they want to know "how do I do x with GLIDE". Thus when documenting a new feature, we recommend starting with a how-to guides on using such feature. This is usually simple and quicker to write, and provide immediate benefits. + +While your how-to guides should have some conceptual explanations, it should remain focused on answering the "how do I do x" question. Having a length explanation can often distract from this. If this is required, it is best to create a separate articles in our Learn sections with the focus on teaching the reader. + +In general, a guide line for how-to articles would be: +- The title should start with a verb. Ex: Installing GLIDE, Making Batch Commands. +- The content is about showing the reader how to doing something. This often involves using code examples. +- Some conceptual explanation is encouraged, but it should not be the focus. From 021b7225b91890b779048a0275e292c75f820599 Mon Sep 17 00:00:00 2001 From: Alex Le Date: Thu, 9 Apr 2026 15:29:31 -0700 Subject: [PATCH 3/8] fixed formatting and removed issue requirements Signed-off-by: Alex Le --- .github/pull_request_template.md | 12 ++---------- CONTRIBUTING.md | 2 ++ README.md | 12 ++---------- 3 files changed, 6 insertions(+), 20 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b24b0494..e4180611 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,9 +1,3 @@ - - ### Summary ### Content Changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3dd1a5d8..98397cbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,7 @@ Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! This guide aims to help answer more conceptual questions about writing documentations like: + - What kind of documentation should I write? - How should I write my documentations? @@ -23,6 +24,7 @@ Users reach for the documentation because they want to know "how do I do x with While your how-to guides should have some conceptual explanations, it should remain focused on answering the "how do I do x" question. Having a length explanation can often distract from this. If this is required, it is best to create a separate articles in our Learn sections with the focus on teaching the reader. In general, a guide line for how-to articles would be: + - The title should start with a verb. Ex: Installing GLIDE, Making Batch Commands. - The content is about showing the reader how to doing something. This often involves using code examples. - Some conceptual explanation is encouraged, but it should not be the focus. diff --git a/README.md b/README.md index 60a652c8..ef6f8c4d 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ Welcome to the Valkey GLIDE documentation repository. The site is available at https://glide.valkey.io. -> **Note:** This repository contains only the documentation of Valkey GLIDE. +> **Note:** This repository contains only the documentation of Valkey GLIDE. > To contribute to the Valkey GLIDE client library itself, visit [valkey-glide](https://github.com/valkey-io/valkey-glide/). ## Overview The site is built with [Starlight](https://starlight.astro.build/), an Astro framework for building static documentation sites. -The framework provides out-of-the-box features for building documentations like UI components, site search, navigation, all using a Markdown like syntax. It also leverages Astro's features to build custom dynamic components. +The framework provides out-of-the-box features for building documentations like UI components, site search, navigation, all using a Markdown like syntax. It also leverages Astro's features to build custom dynamic components. This aims to allow contributors to quickly add or edit existing pages using familiar Markdown syntax, while having the options to extend the site with modern Javascript components. ## Getting Started @@ -52,14 +52,6 @@ For a guidelines on how to write new articles, take a look at our [Contributing] All commits must include the `--signoff` flag to certify the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). -## Making a Pull Request - -Before making a pull request, make sure that you have a corresponding issue created either in this repo or the main Valkey GLIDE source repo. Each pull request should be related to an issue, unless it is a minor fix. - -When making a pull request, please make sure to follow our template and complete the required sections. - -Importantly, ensure that your PR ha - ## Link Checker We use [lychee](https://github.com/lycheeverse/lychee) to check for broken links. Configuration rules (exclusions) are defined in our `lychee.toml`. From 835d01446c6b5e3f1110d53d1d7a912ce193a53e Mon Sep 17 00:00:00 2001 From: Alex Le Date: Thu, 9 Apr 2026 15:32:24 -0700 Subject: [PATCH 4/8] updated PR tempalte Signed-off-by: Alex Le --- .github/pull_request_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e4180611..18ae9b33 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,10 @@ -### Summary +## Summary -### Issue link +### Related Issue -### Content Changes +## Changes + ## Summary + +### Checklist +- [ ] `pnpm build` and `pnpm format` passing locally. +- [ ] All commits are signed off with `--signoff` flag. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01415bf8..30b54329 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,10 @@ Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! -This guide covers conceptual questions about writing documentation: +This guide will cover both conceptual and technical questions about writing documentation: +- How to prepare the environment? +- How do I make a first contribution? - What kind of documentation should I write? - How should I write my documentation? diff --git a/README.md b/README.md index ef6f8c4d..0e326e29 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Page content lives under `src/content/docs/` as `.mdx` files. - **Update the sidebar navigation:** Add your new page to `astro.config.mjs`. -For a guidelines on how to write new articles, take a look at our [Contributing](/CONTRIBUTING.md) page. +For guidelines on how to write new articles, take a look at our [Contributing](/CONTRIBUTING.md) page. ## Commit Requirements From 48f73938985f8a4524987bc4ea7dc06536bc1c6c Mon Sep 17 00:00:00 2001 From: Alex Le Date: Fri, 1 May 2026 16:59:50 -0700 Subject: [PATCH 7/8] Added developer doc Signed-off-by: Alex Le --- DEVELOPER.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 DEVELOPER.md diff --git a/DEVELOPER.md b/DEVELOPER.md new file mode 100644 index 00000000..3fab6404 --- /dev/null +++ b/DEVELOPER.md @@ -0,0 +1,118 @@ +# Developer + +This guide covers the developer workflow for the Valkey GLIDE documentation site. It explains how to set up your environment, build and preview the site locally, check links, and keep your changes formatted and lint-clean before opening a pull request. + +The site is built with [Starlight](https://starlight.astro.build/), an [Astro](https://astro.build/) framework for static documentation sites. Pages are authored in Markdown/MDX under `src/content/docs/`. + +## Requirements + +You will need the following installed locally: + +- [Node.js](https://nodejs.org/) **v20 or newer** +- [pnpm](https://pnpm.io/) **v10 or newer** — install via `brew install pnpm` or `npm install -g pnpm` +- [Git](https://git-scm.com/) — for cloning the repository and committing changes +- [lychee](https://github.com/lycheeverse/lychee) — only required if you want to run the link checker locally (`brew install lychee`) + +### Clone and install + +```bash +git clone git@github.com:valkey-io/valkey-glide-docs.git +cd valkey-glide-docs +pnpm install +``` + +`pnpm install` reads `package.json` / `pnpm-lock.yaml` and installs all dependencies into `node_modules/`. + +## Build + +The project uses `pnpm` scripts defined in `package.json`. The commands you will use most often are listed below. + +### Development server + +Start a local hot-reloading dev server: + +```bash +pnpm dev +``` + +By default Astro serves the site at [http://localhost:4321](http://localhost:4321). Edits to `.mdx` files and components are reflected automatically. + +### Production build + +Build the static site into the `dist/` directory: + +```bash +pnpm build + +# Preview the production build +pnpm preview +``` + +This is the same build that runs in CI. You should run it locally before opening a PR to make sure your changes compile cleanly. See [Pre-PR Checks](#pre-pr-checks) below. + +## Link Checker + +We use [lychee](https://github.com/lycheeverse/lychee) to check for broken links. Configuration rules (exclusions) are defined in our `lychee.toml`. + +To start, install `lychee`. + +```bash +brew install lychee +``` + +Then to run the build and check links: + +```bash +pnpm build:check-links +``` + +This runs `pnpm build` followed by `lychee` against the generated `dist/` directory. The same check runs in CI, so fixing link issues locally will save a round-trip on your PR. + +## Code Style & Formatting + +The project uses [Prettier](https://prettier.io/) for general formatting and [remark](https://github.com/remarkjs/remark) for MDX/Markdown linting. Configuration is in `.prettierrc.json` and `.remarkrc.json`. + +Run formatting before submitting a PR: + +```bash +pnpm format +``` + +This runs two steps: + +- `format:non-mdx` — runs Prettier across the repo (`.astro`, `.ts`, `.json`, etc.). +- `format:mdx` — runs `remark` over `src/content/docs/**/*.{md,mdx}` and applies a small post-processing fix (`scripts/fix-remark-escapes.sh`) to work around over-aggressive escaping in MDX files. + +To check formatting without modifying files: + +```bash +pnpm format:check +``` + +This runs `prettier --check` and then `scripts/check-format.sh`, which wraps `remark` and filters out known false-positive warnings from Starlight's shorthand aside syntax (for example, `[!NOTE]`). CI uses the same script, so if it passes locally it should pass in CI as well. + +## Pre-PR Checks + +Before opening a pull request, always run: + +```bash +pnpm build +pnpm format +``` + +Then commit any changes that `pnpm format` makes. This order matters — build first to catch compile errors, then format to keep the tree consistent. + +### Commit signoff + +All commits must include a Developer Certificate of Origin (DCO) signoff: + +```bash +git commit --signoff -m "Your commit message" + +# Auto sign all commits. Requires git 2.36+ +git config --global format.signOff true +``` + +Make sure `user.name` and `user.email` are configured (`git config user.name` / `git config user.email`) so the signoff line reflects the correct identity. + +> **Note:** The DCO check is **case-sensitive** for both the name and email address. Make sure it matches the trailer produced by your signoff. From cc4be8c6a053953f6cca5641cccfaaf92a6eccc3 Mon Sep 17 00:00:00 2001 From: Alex Le Date: Mon, 4 May 2026 15:39:25 -0700 Subject: [PATCH 8/8] updated md docs Signed-off-by: Alex Le --- CONTRIBUTING.md | 67 ++++++++++++++++++++++++++++++++++++++----------- DEVELOPER.md | 49 ++++++++++-------------------------- README.md | 65 +++++------------------------------------------ 3 files changed, 71 insertions(+), 110 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30b54329..f889a77e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,31 +2,68 @@ Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)! -This guide will cover both conceptual and technical questions about writing documentation: +This guide gets you started on contributing to the documentation. +For the full technical instructions see our [Developer Instructions](/DEVELOPER.md). -- How to prepare the environment? -- How do I make a first contribution? -- What kind of documentation should I write? -- How should I write my documentation? +> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, visit the [valkey-glide repository](https://github.com/valkey-io/valkey-glide/). -For more technical instructions, like how to set up the environment, see our [Readme](/README.md). +## Requirements -> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, visit the [valkey-glide repository](https://github.com/valkey-io/valkey-glide/). +Before continuing, make sure to follow the prerequisite instructions in our [Developer Instructions](/DEVELOPER.md). ## Language Agnostic Documentation The goal of Valkey GLIDE documentation is to be the single source of truth for the various Valkey GLIDE clients. -When writing documentation, consider all client languages. In practice, this is easier than it sounds. Because clients share the same Rust core, they behave similarly and can share documentation, with language-specific code examples included when appropriate. +When writing a documentation page, please consider writing for all client languages. In practice, this is easier than it sounds. Because clients share the same Rust core, they behave similarly and can share documentation, with language-specific code examples included when appropriate. + +## Documenting a New Feature + +When documenting a new feature, we recommend starting with a how-to guide. They are often simpler to write and provide immediate value to the users. + +How-to guides are instructions on how to complete a certain tasks. It can include some conceptual explanation, but should stay focused on the "how" as lengthy explanations can be a distraction. If deeper understanding is needed, you should create separate articles in other sections. + +## Adding Your Contents + +Now that you have some content in mind, making changes to the docs is straightforward. + +Content lives under `src/content/docs/` as `.mdx` files. If you are: + +- **Editing an existing page:** Modify the corresponding `.mdx` file. +- **Adding a new page:** Create a new `.mdx` file under `src/content/docs/`. Every file requires frontmatter: + + ```mdx + --- + title: Your page title + --- + + Your content follows... + ``` + +- **Update the sidebar navigation:** Add your new page to `astro.config.mjs`. + + +## Making a Pull Request + +1. **Run the pre-PR checks:** + + ```bash + pnpm build + pnpm format + ``` + + Commit any formatting changes before pushing. + +2. **Sign off every commit** to certify the [DCO](https://developercertificate.org/): -## Adding Documentation For A New Feature + ```bash + git commit --signoff -m "Your message" + ``` -Users come to the documentation to learn how to do something with GLIDE. When documenting a new feature, we recommend starting with a how-to guide. These are simpler to write and provide immediate value. + Or enable it automatically: `git config format.signOff true`. -How-to guides can include some conceptual explanation, but should stay focused on the "how". Lengthy explanations can be a distraction. If deeper context is needed, create a separate article in our Learn section instead. + The DCO check is **case-sensitive** on name and email — verify with `git log -1 --format='%an <%ae>'`. -Guidelines for how-to articles: +3. **Publish your branch:** Publish your changes and open a PR. -- The title should be an action (e.g., "Installing GLIDE", "Making Batch Commands"). -- The content shows the reader how to do something, often with code examples. -- Some conceptual explanation is encouraged, but it should not be the focus. + Make sure to link your PR to a related issue either in this repo or one of the Valkey GLIDE client repositories. diff --git a/DEVELOPER.md b/DEVELOPER.md index 3fab6404..4a5c7380 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -1,15 +1,15 @@ -# Developer +# Developer Guide -This guide covers the developer workflow for the Valkey GLIDE documentation site. It explains how to set up your environment, build and preview the site locally, check links, and keep your changes formatted and lint-clean before opening a pull request. +This guide covers the developer workflow for the Valkey GLIDE documentation site. -The site is built with [Starlight](https://starlight.astro.build/), an [Astro](https://astro.build/) framework for static documentation sites. Pages are authored in Markdown/MDX under `src/content/docs/`. +The site is built with [Starlight](https://starlight.astro.build/), an [Astro](https://astro.build/) framework for static documentation sites. ## Requirements You will need the following installed locally: - [Node.js](https://nodejs.org/) **v20 or newer** -- [pnpm](https://pnpm.io/) **v10 or newer** — install via `brew install pnpm` or `npm install -g pnpm` +- [pnpm](https://pnpm.io/) **v10 or newer**. [Npm](https://www.npmjs.com/) is fine as well. - [Git](https://git-scm.com/) — for cloning the repository and committing changes - [lychee](https://github.com/lycheeverse/lychee) — only required if you want to run the link checker locally (`brew install lychee`) @@ -21,22 +21,18 @@ cd valkey-glide-docs pnpm install ``` -`pnpm install` reads `package.json` / `pnpm-lock.yaml` and installs all dependencies into `node_modules/`. - ## Build -The project uses `pnpm` scripts defined in `package.json`. The commands you will use most often are listed below. +Various build commands are available. ### Development server -Start a local hot-reloading dev server: +To start a local hot-reloading dev server: ```bash pnpm dev ``` -By default Astro serves the site at [http://localhost:4321](http://localhost:4321). Edits to `.mdx` files and components are reflected automatically. - ### Production build Build the static site into the `dist/` directory: @@ -44,8 +40,8 @@ Build the static site into the `dist/` directory: ```bash pnpm build -# Preview the production build -pnpm preview +# Preview the production build including the search bar. +pnpm preview ``` This is the same build that runs in CI. You should run it locally before opening a PR to make sure your changes compile cleanly. See [Pre-PR Checks](#pre-pr-checks) below. @@ -63,10 +59,11 @@ brew install lychee Then to run the build and check links: ```bash +# Build then check links pnpm build:check-links ``` -This runs `pnpm build` followed by `lychee` against the generated `dist/` directory. The same check runs in CI, so fixing link issues locally will save a round-trip on your PR. +This runs `pnpm build` followed by `lychee` against the generated `dist/` directory. ## Code Style & Formatting @@ -75,33 +72,13 @@ The project uses [Prettier](https://prettier.io/) for general formatting and [re Run formatting before submitting a PR: ```bash +# Apply formatting pnpm format -``` - -This runs two steps: -- `format:non-mdx` — runs Prettier across the repo (`.astro`, `.ts`, `.json`, etc.). -- `format:mdx` — runs `remark` over `src/content/docs/**/*.{md,mdx}` and applies a small post-processing fix (`scripts/fix-remark-escapes.sh`) to work around over-aggressive escaping in MDX files. - -To check formatting without modifying files: - -```bash +# Check format only pnpm format:check ``` -This runs `prettier --check` and then `scripts/check-format.sh`, which wraps `remark` and filters out known false-positive warnings from Starlight's shorthand aside syntax (for example, `[!NOTE]`). CI uses the same script, so if it passes locally it should pass in CI as well. - -## Pre-PR Checks - -Before opening a pull request, always run: - -```bash -pnpm build -pnpm format -``` - -Then commit any changes that `pnpm format` makes. This order matters — build first to catch compile errors, then format to keep the tree consistent. - ### Commit signoff All commits must include a Developer Certificate of Origin (DCO) signoff: @@ -113,6 +90,6 @@ git commit --signoff -m "Your commit message" git config --global format.signOff true ``` -Make sure `user.name` and `user.email` are configured (`git config user.name` / `git config user.email`) so the signoff line reflects the correct identity. +Make sure `user.name` and `user.email` are configured correctly to reflect your credentials. > **Note:** The DCO check is **case-sensitive** for both the name and email address. Make sure it matches the trailer produced by your signoff. diff --git a/README.md b/README.md index 0e326e29..0b5ddc0c 100644 --- a/README.md +++ b/README.md @@ -14,72 +14,19 @@ This aims to allow contributors to quickly add or edit existing pages using fami ## Getting Started -You'll need the following installed: - -- [Node.js](https://nodejs.org/) v20+ -- [pnpm](https://pnpm.io/) v10+ (`brew install pnpm` or `npm install -g pnpm`) - -Then clone the repo and install dependencies: +Clone the repo and install dependencies with npm: ```bash git clone git@github.com:valkey-io/valkey-glide-docs.git cd ./valkey-glide-docs pnpm install -``` - -For development, run `pnpm dev`. It will spin up a hot-loading development server to serve the documentation pages. - -### Making Changes - -Page content lives under `src/content/docs/` as `.mdx` files. - -- **Edit a page:** Modify the corresponding `.mdx` file. -- **Add a new page:** Create a new `.mdx` file under `src/content/docs/`. Every file requires frontmatter: - - ```mdx - --- - title: Your page title - --- - - Your content follows... - ``` - -- **Update the sidebar navigation:** Add your new page to `astro.config.mjs`. - -For guidelines on how to write new articles, take a look at our [Contributing](/CONTRIBUTING.md) page. - -## Commit Requirements - -All commits must include the `--signoff` flag to certify the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). - -## Link Checker -We use [lychee](https://github.com/lycheeverse/lychee) to check for broken links. Configuration rules (exclusions) are defined in our `lychee.toml`. - -To start, install `lychee`. - -```bash -brew install lychee -``` - -Then to run the build and check links: - -```bash -pnpm build:check-links +# Start a hot-loading dev server. +pnpm dev ``` -## Code Style & Formatting +See [DEVELOPER](DEVELOPER.md) for the full developer instructions. -The project uses [Prettier](https://prettier.io/) for general formatting and [remark](https://github.com/remarkjs/remark) for MDX/Markdown linting. Configuration is in `.prettierrc.json` and `.remarkrc.json`. +## Making Changes -Run formatting before submitting a PR: - -```bash -pnpm format -``` - -To check formatting without modifying files: - -```bash -pnpm format:check -``` +For more on making your first contribution, see our [CONTRIBUTING](CONTRIBUTING.md) page.