Migration

.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 80

.github/instructions/docs.instructions.md

@@ -0,0 +1,11 @@
+---
+applyTo: "docs/**/*.mdx, !docs/api/**/*.mdx"
+---
+
+Focus on documentation clarity and accuracy, ensuring that instructions are easy
+to follow and understand by a technical audience. Avoid suggesting changes that
+involve deleting existing content unless it is outdated or incorrect.
+
+When making changes to the documentation, be sure to honor the settings in .editorconfig.
+When editing markdown or .MDX files, ignore the line length limit in bullet points, tables,
+code blocks and front-matter.

.github/workflows/ci.yml

@@ -16,22 +16,30 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - name: Checkout code
+      - name: 📥 Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 2
 
-      - name: Set up Node.js
+      - name: 📦 Setup pnpm package manager
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: 🟢 Setup Node.js runtime
         uses: actions/setup-node@v4
         with:
-          node-version: "22"
-
-      - name: Check for broken links
-        run: |
-          set -e
-          output=$(npx mint broken-links)
-          echo "$output"
-          if ! echo "$output" | grep -q '^success '; then
-            echo "Error: Broken links found! Fix the broken links listed above before merging."
-            exit 1
-          fi
+          node-version-file: ".nvmrc"
+          cache: "pnpm"
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: 📚 Install project dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: ✅ Check types
+        run: pnpm check:type
+
+      - name: 🏗️ Build
+        run: pnpm build

.github/workflows/docs-to-vector.yml

@@ -24,20 +24,20 @@ jobs:
             }')
 
           echo "$payload" > /tmp/payload.json
-          
+
       - name: Connect to company network
         uses: tailscale/github-action@v3
         with:
           oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
           oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
           tags: tag:ci
-      
+
       - name: Call Webhook (Preview)
         run: |
           payload=$(cat /tmp/payload.json)
           sig=$(printf '%s' "$payload" | \
               openssl dgst -sha256 -hmac "${{ secrets.VECTOR_WEBHOOK_SECRET_PREVIEW }}" -binary | xxd -p -c 256)
-          
+
           curl -X POST \
             -H "Content-Type: application/json" \
             -H "X-Hub-Signature-256: sha256=$sig" \
@@ -50,7 +50,7 @@ jobs:
           payload=$(cat /tmp/payload.json)
           sig=$(printf '%s' "$payload" | \
               openssl dgst -sha256 -hmac "${{ secrets.VECTOR_WEBHOOK_SECRET }}" -binary | xxd -p -c 256)
-          
+
           if [ "${{ secrets.VECTOR_WEBHOOK_URL }}" != "none" ]; then
             curl -X POST \
               -H "Content-Type: application/json" \

.gitignore

@@ -28,8 +28,9 @@ yarn-error.log*
 # local env files
 .env*.local
 .env
+
 # vercel
 .vercel
 
-# lock files
-package-lock.json
+# docusaurus
+/.docusaurus

.nvmrc

@@ -0,0 +1 @@
+lts/jod

.prettierignore

@@ -0,0 +1,8 @@
+docs/api/
+api-spec/
+build/
+.docusaurus/
+node_modules/
+pnpm-lock.yaml
+static/**/*.webmanifest
+old/

.prettierrc

@@ -0,0 +1,5 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

CONTRIBUTING.md

@@ -1,52 +1,118 @@
-# Contribution Guide for Plane Docs
+# Contribution Guide
 
-Thank you for considering contributing to Plane docs! Your contributions help improve the quality and accessibility of our documentation for all users. Please follow the guidelines outlined below to ensure a smooth contribution process.
+Thank you for considering contributing to the Plane developer documentation!
+Your contributions help improve the quality and accessibility of our
+documentation for all users. Please follow the guidelines outlined below to
+ensure a smooth contribution process.
 
-### 1. Create a New Issue (if it doesn't exist)
-If you encounter a problem or wish to suggest an improvement in the documentation that hasn't been addressed yet, please create a new issue. Be sure to check existing issues to avoid duplication. Include a clear description of the problem or enhancement you're suggesting.
+## 1. Create a new issue
 
-### 2. Create a New Branch from Master
-Before making any changes, create a new branch from the `master` branch. This branch will contain your proposed changes and keep the `master` branch clean for stable releases.
+If you encounter a problem or wish to suggest an improvement in the
+documentation that hasn't been addressed yet, please create a [new issue](https://github.com/makeplane/developer-docs/issues/new). Be sure
+to check existing [issues](https://github.com/makeplane/developer-docs/issues) to avoid duplication. Include a clear description of
+the problem or enhancement you're suggesting.
+
+## 2. Contributing
+
+To contribute your changes, you have two options:
+
+1. Edit the files directly on Github
+   - Perfect for small, single-file changes. This is the easiest option but you
+     won't be able quickly iterate on your changes with a running server.
+1. Run this site locally
+   - Excellent for any size of change.
+
+## Option 1 - Edit on Github
+
+1. While viewing our docs on [developers.plane.so](https://developers.plane.so), navigate to the page you want to change. Scroll to the bottom and click the 'Edit this page' link.
+2. If prompted, click the 'Fork this repository' button
+3. Make your edits
+4. Click the 'Commit changes' button
+5. Fill out the form, making sure the 'Commit message' is short and meaningful.
+   In the 'Extended description' field, be sure to reference the related issue
+   using GitHub's syntax (`#123`). This links your Pull Request to the
+   issue and helps us understand your reason for the changes.
+6. Click 'Propose changes'
+7. Click the 'Create pull request' button
+
+## Option 2 - Edit locally
+
+Follow these steps to run this site and make your changes locally.
+
+### 1. Clone this repository
 
 ```bash
-git checkout master
-git pull origin master
+git clone [email protected]:makeplane/developer-docs.git && cd developer-docs
+```
+
+### 2. Create a new branch
+
+Before making any changes, create a new branch from the `main` branch. This
+branch will contain your proposed changes and keep the `main` branch clean for
+stable releases.
+
+```bash
+git checkout main
+git pull origin main
 git checkout -b <branch-name>
 ```
 
-### 3. Make Changes in the Appropriate Page
-Navigate to the relevant documentation page in the repository and make your changes. Ensure that your changes align with our style guide and maintain consistency across the documentation.
+Next, install the dependencies.
+
+```bash
+corepack enable pnpm
+pnpm install
+```
+
+### 3. Run the site locally
+
+Start up a local development server so you can preview your changes before submitting them for review.
+
+```bash
+pnpm dev
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+#### About this site
 
-### 4. Preview your changes
-Make sure you are visually happy with your changes.
+This site is built using [Docusaurus](https://docusaurus.io/), an open source
+static website generator along with
+[docusaurus-openapi-docs](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs).
 
-1. Run `npx mint dev`
-1. A url will be printed to your console. Open it in your browser.
-1. Visit your pages and confirm they look correct.
+To find out which directories are served at which routes, [read this](https://docusaurus.io/docs/next/advanced/routing).
 
-### 5. Fix broken links
+### 4. Make changes
 
-1. Run `npx mint broken-links`
-2. Fix all reported broken links
+Open the relevant documentation file and make your changes. Using your local
+browser, review that your changes look as you expect and they align with our
+current styles and tone across the documentation.
 
-### 6. Raise a Pull Request (PR)
-Once your changes are ready, raise a pull request (PR) to merge your branch into the `master` branch. Please provide a descriptive title and detailed description of your changes.
+**Warning**: All files in `docs/api/*` are auto-generated. Do not edit by hand.
 
-### 7. Leave a Clear Commit Message
-When committing your changes, leave a clear and concise message that links to the corresponding issue (if applicable) and explains the fix or enhancement you've made.
+### 5. Commit your changes
+
+When committing your changes, leave a clear and concise message that links to
+the corresponding issue (if applicable) and explains the fix or enhancement
+you've made.
 
 ```bash
 git add .
 git commit -m "Fixes #<issue-number>: Description of the fix or enhancement"
 ```
 
-### 8. Link the Issue to the Pull Request
+### 6. Link the Issue to the Pull Request
+
 In your pull request description, be sure to reference the related issue using GitHub's syntax (`#<issue-number>`). This links the PR to the issue and helps maintain context.
 
-### 9. Sign the Contributor License Agreement (CLA)
+### 7. Sign the Contributor License Agreement (CLA)
+
 Before we can merge your contribution, you must sign our contributor license agreement (CLA). This agreement ensures that your contributions comply with our licensing terms.
 
-### 10. Assign a Reviewer from Our Team
-Once your PR is submitted, a member of our team will be assigned to review your changes. They will provide feedback and may request revisions if necessary. Please respond promptly to any review comments to expedite the merging process.
+### 8. Reviews
+
+Once your Pull Request is submitted, a member of our team will be assigned to review your changes. They will provide feedback and may request revisions if necessary. Please respond promptly to any review comments to expedite the review and acceptance process.
+
+## Thank you!
 
-Thank you for contributing to our documentation! We appreciate your efforts in making our product documentation more comprehensive and user-friendly. If you have any questions or need assistance, feel free to reach out to our team. Happy contributing!
+Thank you for contributing to our documentation! We greatly appreciate your efforts to help improve the Plane community.

README.md

@@ -1,29 +1,19 @@
 # Plane developer documentation
 
-This repository hosts comprehensive developer documentation for Plane, accessible at [developers.plane.so](https://developers.plane.so). If you are looking for the product documentation, see [Plane documentation](https://github.com/makeplane/docs)
+This repository hosts comprehensive developer documentation for Plane, accessible at [developers.plane.so](https://developers.plane.so). If you are looking for the product documentation, see [Plane documentation](https://github.com/makeplane/docs).
 
-## Overview
-
-The Plane documentation provides detailed information on the following topics:
-
-- Setting up and managing a self-hosted instance of Plane.
-- API Reference
-- Webhooks
-
-## Raising Issues
+## Raising issues
 
 If you encounter any issues with our documentation or have suggestions for improvements, we encourage you to follow these steps:
 
-1. **Check Existing Issues**: Before raising a new issue, please verify if a similar issue already exists.
-2. **Raise an Issue**: If you don't find an existing issue that matches your concern, feel free to create a new one. Provide as much detail as possible to clearly explain the problem or enhancement you're proposing.
+1. **Check existing issues**: Before raising a new issue, please verify if a [similar issue](https://github.com/makeplane/developer-docs/issues) already exists.
+2. **Raise an issue**: If you don't find an existing issue that matches your concern, feel free to [create a new one](https://github.com/makeplane/developer-docs/issues/new). Provide as much detail as possible to clearly explain the problem or enhancement you're proposing.
 
 ## Contributing
 
 Are you interested in contributing to our documentation? We welcome contributions from the community! You can contribute by:
 
-- Fixing bugs in the existing documentation.
-- Adding new guides or tutorials.
+- Fixing bugs in the existing documentation
+- Adding new guides or tutorials
 
 To get started with contributing, please refer to our [Contribution Guide](/CONTRIBUTING.md). We appreciate contributions related to self-hosting, core product functionality, and integrations with other applications.
-
-Thank you for considering contributing to Plane documentation. Your contributions help improve the overall user experience and make information more accessible to all users. Let's work together to make Plane documentation even better!

_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Overview",
+  "position": 1,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index"
+  }
+}