Skip to content

Commit 9bf2a26

Browse files
claudiacodacyclaudiacodacy
authored
New doc framework (#1)
* 5 million changes * moved imports to another folder * fix old docs * update favicons * Update logo * adding remark ids for mdx files * yaml quick fix on quick start + id fixes * revamp starter page * adjust title height + move home sidebar * navbar color * add footer + social icons * change base font-size * added todo file * added tabs with starlight-sidebar-topics * sidebar fixes + last updated date + versioning doc * update todo * fix quick start in prod * paid includes + review markdown * sidebar collapse + import fix * update ide getting started into folder * get started ide folder * fix active tab * codacy-api markdown to mdx * using codacy-api to mdx * codacy api example : adding repos * transfer all codacy-api * docs guardrails * changed all asides * removing all first titles * moved all Id attributes to new format * migrate all includes * trying out docusaurus instead * fixed imports + all mdx / md formatting * two tabs in docusaurus * reorder sidebar items * release notes sidebar * logos + fav + homepage * delete starlight from pr * updated todo list * update todo * theme: use inter * Inter + sidebar adjustments * color variables * css organize * review greys * content footer * remove breadcrumbs * center content in page * remove github from navbar * adding search * adjust css file * convert all imports to mdx * fix image in imports * update docs * update todo * navbar theme * adding docusaurus gh action + disabling mkdocs
1 parent ec8e09d commit 9bf2a26

File tree

596 files changed

+39554
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

596 files changed

+39554
-0
lines changed

‎.github/workflows/docusaurus.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Deploy Docusaurus to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [ master ]
6+
paths:
7+
- docusaurus/**
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
deploy:
19+
runs-on: ubuntu-latest
20+
defaults:
21+
run:
22+
working-directory: docusaurus
23+
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Setup Node
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: 20
32+
cache: npm
33+
cache-dependency-path: docusaurus/package-lock.json
34+
35+
- name: Install
36+
run: npm ci
37+
38+
- name: Build
39+
run: npm run build
40+
41+
- name: Deploy to gh-pages
42+
uses: peaceiris/actions-gh-pages@v4
43+
with:
44+
github_token: ${{ secrets.GITHUB_TOKEN }}
45+
publish_dir: docusaurus/build
46+
publish_branch: gh-pages-docusaurus

.github/workflows/mkdocs.yml renamed to .github/workflows/mkdocs.yml.disabled

File renamed without changes.

.github/workflows/scheduled.yml renamed to .github/workflows/scheduled.yml.disabled

File renamed without changes.

.github/workflows/vale.yml renamed to .github/workflows/vale.yml.disabled

File renamed without changes.

‎docusaurus/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docusaurus/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
## Installation
6+
7+
```bash
8+
yarn
9+
```
10+
11+
## Local Development
12+
13+
```bash
14+
yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
## Build
20+
21+
```bash
22+
yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
## Deployment
28+
29+
Using SSH:
30+
31+
```bash
32+
USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```bash
38+
GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
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.

‎docusaurus/TODO‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
MkDocs ➜ Docusaurus migration checklist
2+
3+
Goal: ship `docusaurus/` as the new production site for https://docs.codacy.com/
4+
5+
---
6+
MVP
7+
8+
## 0) Make it beautiful
9+
- [x] Colors, fonts and sizes
10+
- [x] Better footer
11+
- [x] Beautiful navigation
12+
- [x] Nav links
13+
14+
## 0) Apply new theme!
15+
- [ ] Homepage
16+
- [ ] Sidebar
17+
- [x] Navbar
18+
- [ ] Search
19+
- [ ] Footer
20+
- [ ] Nav buttons
21+
- [ ] Reading time?
22+
23+
## 1) Content parity (docs rendering)
24+
- [ ] Confirm all pages exist in `docusaurus/docs` (count + spot-check key sections)
25+
- [x] Confirm MkDocs-only templating is fully removed from Docusaurus content:
26+
- [x] No Jinja tags (`{% ... %}` / `{{ ... }}`) remain in `docusaurus/docs`
27+
- [x] Replace MkDocs `extra.*` variables with Docusaurus equivalents (MDX constants / front matter / config)
28+
- [x] Confirm MkDocs `include-markdown` usage is fully replaced with `_includes/*.mdx` imports/usages
29+
- [x] Confirm admonitions render as expected (MkDocs `!!! note|tip|warning` ➜ Docusaurus admonitions / MDX syntax)
30+
- [ ] Confirm heading IDs/anchors are stable (MkDocs `toc` permalink + custom `{:#id}` usage)
31+
- [ ] Fix all the links
32+
33+
## 2) Navigation & information architecture
34+
- [ ] Review `docusaurus/sidebars.ts` vs MkDocs `nav:` in `mkdocs.yml` for:
35+
- [ ] Missing/extra categories
36+
- [ ] Ordering (including release notes yearly grouping)
37+
- [ ] Any pages that should be hidden from sidebar but still routable
38+
- [x] Replace placeholder site metadata in `docusaurus/docusaurus.config.ts` (title/tagline/footer links/GitHub links)
39+
- [x] Decide canonical doc routes (Docusaurus uses `/` as `routeBasePath`): ensure this matches production expectations
40+
---
41+
42+
Releseable
43+
44+
## 3) Redirects (must-have before cutover)
45+
- [ ] Port MkDocs `redirect_maps` from `mkdocs.yml` to Docusaurus redirects
46+
- Recommended: add `@docusaurus/plugin-client-redirects` and generate redirects from `mkdocs.yml`
47+
- Include legacy Zendesk (`hc/...`) redirects and internal moved-page redirects
48+
- [ ] Validate redirects with a link/redirect checker against the built site
49+
50+
## 5) Release notes specifics
51+
- [ ] RSS feed parity (MkDocs uses `mkdocs-rss-plugin` for `release-notes/*`)
52+
- [ ] Decide feed generation approach (Docusaurus plugin/custom script during build)
53+
- [ ] Ensure `/feed_rss_created.xml` exists (many pages link to it)
54+
- [ ] Confirm release notes sidebar + navigation matches expectations (tabs already added)
55+
56+
## 8) SEO & meta descriptions (replaces `mkdocs-meta-descriptions`)
57+
- [ ] Decide how to generate meta descriptions (front matter `description` / plugin / build-time extraction)
58+
- [ ] Preserve sitemap + robots behavior (MkDocs workflow wrote `robots.txt` with sitemap link)
59+
- [ ] Validate canonical URLs and avoid indexing preview builds (MkDocs used preview banner + env toggles)
60+
61+
## 9) CI/CD parity (replaces `.github/workflows/mkdocs.yml`)
62+
- [ ] Add a Docusaurus workflow that covers:
63+
- [ ] Build
64+
- [ ] HTML/link validation equivalent to `htmltest` + `lychee` expectations
65+
- [ ] Branch previews (Netlify or equivalent)
66+
- [ ] Deploy latest to `gh-pages` with `CNAME=docs.codacy.com`
67+
- [ ] Deploy versioned Self-hosted docs from `release/v*`
68+
69+
---
70+
71+
NEXT
72+
73+
## 4) Versioning strategy (replaces `mike` + `MKDOCS_SELF_HOSTED`)
74+
MkDocs currently publishes:
75+
- Latest docs on `master` to `gh-pages/`
76+
- Self-hosted versions from `release/v*` using `mike deploy ...` (and `MKDOCS_SELF_HOSTED=true`)
77+
78+
- [ ] Decide Docusaurus versioning model:
79+
- [ ] Use Docusaurus docs versions for Self-hosted (`release/v*` ➜ versioned docs)
80+
- [ ] Decide URL shape for versions (must preserve/redirect existing production URLs)
81+
- [ ] Implement the model in CI (build + deploy) and document how to cut a new Self-hosted version
82+
- [ ] Re-implement any “version selector” behavior (MkDocs `assets/javascripts/version-select.js` + CSS)
83+
84+
## 6) “Last updated” (replaces `git-revision-date-localized`)
85+
- [ ] Enable/verify “Last updated” on doc pages (date + author if desired)
86+
- [ ] Ensure CI checkout uses full git history (`fetch-depth: 0`) so last update data is correct
87+
88+
## 7) Tracking, scripts, and UX widgets
89+
MkDocs uses `extra.segment_key`, `extra.user_feedback`, and custom JS/CSS.
90+
- [ ] Add tracking (Segment or chosen tool) to Docusaurus
91+
- [ ] Add Zendesk
92+
- [ ] Re-implement “user feedback” if it was a widget on MkDocs
93+
94+
## 10) Cleanup & documentation for contributors
95+
- [ ] Update root `README.md` and `CONTRIBUTING.md` for Docusaurus (build/preview instructions)
96+
- [ ] Decide what to do with MkDocs artifacts once cutover is complete:
97+
- [ ] `mkdocs.yml`, `requirements.txt`, MkDocs workflows
98+
- [ ] MkDocs theme submodule `submodules/codacy-mkdocs-material`
99+
100+
## 11) Update release script
101+
- [ ] Update release script

‎docusaurus/docs/_includes/AdminAccessControlInfo.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
:::note
2+
Organization admins can [manage access to this feature](/organizations/roles-and-permissions-for-organizations#change-analysis-configuration)
3+
:::

‎docusaurus/docs/_includes/AdminAccessInfo.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
:::note
2+
Only organization admins can update this setting.
3+
:::

‎docusaurus/docs/_includes/AiInfo.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
:::note
2+
- This feature is compatible with most programming languages and requires no additional setup.
3+
- Comments are generated using the description of the static analysis issue, information about the tool that detected the issue, and a few lines of surrounding code to provide the AI with extra context and improve its accuracy.
4+
- This feature leverages the OpenAI API. No information is shared with other third parties or used to train AI models. Refer to the [OpenAI API data usage policies](https://openai.com/policies/api-data-usage-policies) for more information.
5+
:::

0 commit comments

Comments
 (0)