shadowmkj · shadowmkj · Aug 8, 2026 · Aug 7, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,57 @@
+name: Deploy Docusaurus to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - feat/docs
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build Docusaurus site
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,5 @@
 /target
 Makefile
 *.py
-*.json
 !README.md
+ai_docs/
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,43 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+npm install
+```
+
+**Note**: feel free to use the package manager of your choice.
+
+## Local Development
+
+```bash
+npm run start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true npm run deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> npm run deploy
+```
+
+If you are using GitHub Pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docs/blog/2019-05-28-first-blog-post.mdx b/docs/blog/2019-05-28-first-blog-post.mdx
@@ -0,0 +1,12 @@
+---
+slug: first-blog-post
+title: First Blog Post
+authors: [slorber, yangshun]
+tags: [hola, docusaurus]
+---
+
+Lorem ipsum dolor sit amet...
+
+{/* truncate */}
+
+...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/blog/2019-05-29-long-blog-post.mdx b/docs/blog/2019-05-29-long-blog-post.mdx
@@ -0,0 +1,44 @@
+---
+slug: long-blog-post
+title: Long Blog Post
+authors: yangshun
+tags: [hello, docusaurus]
+---
+
+This is the summary of a very long blog post,
+
+Use a `{/*` `truncate` `*/}` comment to limit blog post size in the list view.
+
+{/* truncate */}
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/blog/2021-08-01-mdx-blog-post.mdx b/docs/blog/2021-08-01-mdx-blog-post.mdx
@@ -0,0 +1,24 @@
+---
+slug: mdx-blog-post
+title: MDX Blog Post
+authors: [slorber]
+tags: [docusaurus]
+---
+
+Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
+
+:::tip
+
+Use the power of React to create interactive blog posts.
+
+:::
+
+{/* truncate */}
+
+For example, use JSX to create an interactive button:
+
+```js
+<button onClick={() => alert('button clicked!')}>Click me!</button>
+```
+
+<button onClick={() => alert('button clicked!')}>Click me!</button>
diff --git a/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
diff --git a/docs/blog/2021-08-26-welcome/index.mdx b/docs/blog/2021-08-26-welcome/index.mdx
@@ -0,0 +1,29 @@
+---
+slug: welcome
+title: Welcome
+authors: [slorber, yangshun]
+tags: [facebook, hello, docusaurus]
+---
+
+[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
+
+Here are a few tips you might find useful.
+
+{/* truncate */}
+
+Simply add Markdown files (or folders) to the `blog` directory.
+
+Regular blog authors can be added to `authors.yml`.
+
+The blog post date can be extracted from filenames, such as:
+
+- `2019-05-30-welcome.md`
+- `2019-05-30-welcome/index.md`
+
+A blog post folder can be convenient to co-locate blog post images:
+
+![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
+
+The blog supports tags as well!
+
+**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.
diff --git a/docs/blog/authors.yml b/docs/blog/authors.yml
@@ -0,0 +1,25 @@
+yangshun:
+  name: Yangshun Tay
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  url: https://linkedin.com/in/yangshun
+  image_url: https://github.com/yangshun.png
+  page: true
+  socials:
+    x: yangshunz
+    linkedin: yangshun
+    github: yangshun
+    newsletter: https://www.greatfrontend.com
+
+slorber:
+  name: Sébastien Lorber
+  title: Docusaurus maintainer
+  url: https://sebastienlorber.com
+  image_url: https://github.com/slorber.png
+  page:
+    # customize the url of the author page at /blog/authors/<permalink>
+    permalink: '/all-sebastien-lorber-articles'
+  socials:
+    x: sebastienlorber
+    linkedin: sebastienlorber
+    github: slorber
+    newsletter: https://thisweekinreact.com
diff --git a/docs/blog/tags.yml b/docs/blog/tags.yml
@@ -0,0 +1,19 @@
+facebook:
+  label: Facebook
+  permalink: /facebook
+  description: Facebook tag description
+
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description
+
+docusaurus:
+  label: Docusaurus
+  permalink: /docusaurus
+  description: Docusaurus tag description
+
+hola:
+  label: Hola
+  permalink: /hola
+  description: Hola tag description
diff --git a/docs/docs/architecture/api-and-graphql.md b/docs/docs/architecture/api-and-graphql.md
@@ -0,0 +1,49 @@
+---
+id: api-and-graphql
+title: API & GraphQL Integration
+sidebar_position: 2
+---
+
+# 🌐 API & GraphQL Integration
+
+`leetrs` communicates directly with LeetCode's backend endpoints using `reqwest` over HTTPS.
+
+---
+
+## 🔑 Authentication & Headers
+
+Every request issued by `LeetCodeClient` attaches:
+1. `Cookie: LEETCODE_SESSION=<session>; csrftoken=<token>`
+2. `x-csrftoken: <token>`
+3. `Referer: https://leetcode.com`
+4. `User-Agent: Mozilla/5.0 ...`
+
+---
+
+## 📡 GraphQL Endpoint
+
+`leetrs` uses LeetCode's central GraphQL endpoint (`https://leetcode.com/graphql`) for:
+- **`problemsetQuestionList`**: Fetching problem list, difficulty, solved status, and topic tags.
+- **`questionData`**: Fetching detailed problem description HTML and language-specific code snippets.
+- **`userStatus`**: Fetching user profile info (username, premium status).
+
+### GraphQL Payload Structure
+
+```json
+{
+  "query": "query questionData($titleSlug: String!) { question(titleSlug: $titleSlug) { questionId title titleSlug content codeSnippets { lang langSlug code } } }",
+  "variables": {
+    "titleSlug": "two-sum"
+  },
+  "operationName": "questionData"
+}
+```
+
+---
+
+## ⚡ Judge REST Endpoints
+
+Code execution and submission utilize LeetCode's REST API:
+- **`POST https://leetcode.com/problems/<slug>/interpret_solution/`**: Submits code for testing sample test cases.
+- **`POST https://leetcode.com/problems/<slug>/submit/`**: Submits code for official judging.
+- **`GET https://leetcode.com/submissions/detail/<interpret_id>/check/`**: Asynchronously polls execution status.
diff --git a/docs/docs/architecture/caching-and-storage.md b/docs/docs/architecture/caching-and-storage.md
@@ -0,0 +1,30 @@
+---
+id: caching-and-storage
+title: Caching & Storage
+sidebar_position: 3
+---
+
+# 💾 Caching & Local Storage
+
+`leetrs` minimizes network latency by maintaining a local disk cache for problem metadata and credentials.
+
+---
+
+## 📁 Data Storage Layout
+
+| Resource | Path Location | Description |
+|---|---|---|
+| **Config** | `~/.config/leetrs/config.toml` | User preferences (`editor`, `language`, `show_description`) |
+| **Credentials** | `~/.config/leetrs/credentials.json` | Active session tokens (`csrftoken`, `session_cookie`) |
+| **Problem Cache** | `~/.local/share/leetrs/data.json` | Cached problem summaries, difficulties, acceptance, and topic tags |
+
+---
+
+## ⚡ Cache Service Mechanics (`src/cache.rs`)
+
+1. **First Run / Cache Miss**: When `leetrs tui` or `list_problems()` is called for the first time, `CacheService` queries LeetCode GraphQL API to fetch the full problem list and writes it to `data.json`.
+2. **Cache Hit**: On subsequent launches, `data.json` is deserialized instantly into memory, reducing boot time to under 10 milliseconds.
+3. **Cache Invalidation**: To force a fresh problem synchronization:
+   ```bash
+   rm -rf ~/.local/share/leetrs/data.json
+   ```