maybe trying out a new docs framework

docusaurus/.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*

docusaurus/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn 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
+yarn 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 yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn 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.

docusaurus/TODO

@@ -0,0 +1,101 @@
+MkDocs ➜ Docusaurus migration checklist
+
+Goal: ship `docusaurus/` as the new production site for https://docs.codacy.com/
+
+---
+MVP
+
+## 0) Make it beautiful
+- [x] Colors, fonts and sizes
+- [x] Better footer
+- [x] Beautiful navigation
+- [x] Nav links
+
+## 0) Apply new theme!
+- [ ] Homepage
+- [ ] Sidebar
+- [x] Navbar
+- [ ] Search
+- [ ] Footer
+- [ ] Nav buttons
+- [ ] Reading time?
+
+## 1) Content parity (docs rendering)
+- [ ] Confirm all pages exist in `docusaurus/docs` (count + spot-check key sections)
+- [x] Confirm MkDocs-only templating is fully removed from Docusaurus content:
+  - [x] No Jinja tags (`{% ... %}` / `{{ ... }}`) remain in `docusaurus/docs`
+  - [x] Replace MkDocs `extra.*` variables with Docusaurus equivalents (MDX constants / front matter / config)
+- [x] Confirm MkDocs `include-markdown` usage is fully replaced with `_includes/*.mdx` imports/usages
+- [x] Confirm admonitions render as expected (MkDocs `!!! note|tip|warning` ➜ Docusaurus admonitions / MDX syntax)
+- [ ] Confirm heading IDs/anchors are stable (MkDocs `toc` permalink + custom `{:#id}` usage)
+- [ ] Fix all the links
+
+## 2) Navigation & information architecture
+- [ ] Review `docusaurus/sidebars.ts` vs MkDocs `nav:` in `mkdocs.yml` for:
+  - [ ] Missing/extra categories
+  - [ ] Ordering (including release notes yearly grouping)
+  - [ ] Any pages that should be hidden from sidebar but still routable
+- [x] Replace placeholder site metadata in `docusaurus/docusaurus.config.ts` (title/tagline/footer links/GitHub links)
+- [x] Decide canonical doc routes (Docusaurus uses `/` as `routeBasePath`): ensure this matches production expectations
+---
+
+Releseable
+
+## 3) Redirects (must-have before cutover)
+- [ ] Port MkDocs `redirect_maps` from `mkdocs.yml` to Docusaurus redirects
+  - Recommended: add `@docusaurus/plugin-client-redirects` and generate redirects from `mkdocs.yml`
+  - Include legacy Zendesk (`hc/...`) redirects and internal moved-page redirects
+- [ ] Validate redirects with a link/redirect checker against the built site
+
+## 5) Release notes specifics
+- [ ] RSS feed parity (MkDocs uses `mkdocs-rss-plugin` for `release-notes/*`)
+  - [ ] Decide feed generation approach (Docusaurus plugin/custom script during build)
+  - [ ] Ensure `/feed_rss_created.xml` exists (many pages link to it)
+- [ ] Confirm release notes sidebar + navigation matches expectations (tabs already added)
+
+## 8) SEO & meta descriptions (replaces `mkdocs-meta-descriptions`)
+- [ ] Decide how to generate meta descriptions (front matter `description` / plugin / build-time extraction)
+- [ ] Preserve sitemap + robots behavior (MkDocs workflow wrote `robots.txt` with sitemap link)
+- [ ] Validate canonical URLs and avoid indexing preview builds (MkDocs used preview banner + env toggles)
+
+## 9) CI/CD parity (replaces `.github/workflows/mkdocs.yml`)
+- [ ] Add a Docusaurus workflow that covers:
+  - [ ] Build
+  - [ ] HTML/link validation equivalent to `htmltest` + `lychee` expectations
+  - [ ] Branch previews (Netlify or equivalent)
+  - [ ] Deploy latest to `gh-pages` with `CNAME=docs.codacy.com`
+  - [ ] Deploy versioned Self-hosted docs from `release/v*`
+
+---
+
+NEXT
+
+## 4) Versioning strategy (replaces `mike` + `MKDOCS_SELF_HOSTED`)
+MkDocs currently publishes:
+- Latest docs on `master` to `gh-pages/`
+- Self-hosted versions from `release/v*` using `mike deploy ...` (and `MKDOCS_SELF_HOSTED=true`)
+
+- [ ] Decide Docusaurus versioning model:
+  - [ ] Use Docusaurus docs versions for Self-hosted (`release/v*` ➜ versioned docs)
+  - [ ] Decide URL shape for versions (must preserve/redirect existing production URLs)
+- [ ] Implement the model in CI (build + deploy) and document how to cut a new Self-hosted version
+- [ ] Re-implement any “version selector” behavior (MkDocs `assets/javascripts/version-select.js` + CSS)
+
+## 6) “Last updated” (replaces `git-revision-date-localized`)
+- [ ] Enable/verify “Last updated” on doc pages (date + author if desired)
+- [ ] Ensure CI checkout uses full git history (`fetch-depth: 0`) so last update data is correct
+
+## 7) Tracking, scripts, and UX widgets
+MkDocs uses `extra.segment_key`, `extra.user_feedback`, and custom JS/CSS.
+- [ ] Add tracking (Segment or chosen tool) to Docusaurus
+- [ ] Add Zendesk
+- [ ] Re-implement “user feedback” if it was a widget on MkDocs
+
+## 10) Cleanup & documentation for contributors
+- [ ] Update root `README.md` and `CONTRIBUTING.md` for Docusaurus (build/preview instructions)
+- [ ] Decide what to do with MkDocs artifacts once cutover is complete:
+  - [ ] `mkdocs.yml`, `requirements.txt`, MkDocs workflows
+  - [ ] MkDocs theme submodule `submodules/codacy-mkdocs-material`
+
+## 11) Update release script
+- [ ] Update release script

docusaurus/docs/_includes/AdminAccessControlInfo.mdx

@@ -0,0 +1,3 @@
+:::note
+Organization admins can [manage access to this feature](/organizations/roles-and-permissions-for-organizations#change-analysis-configuration)
+:::

docusaurus/docs/_includes/AdminAccessInfo.mdx

@@ -0,0 +1,3 @@
+:::note
+Only organization admins can update this setting.
+:::

docusaurus/docs/_includes/AiInfo.mdx

@@ -0,0 +1,5 @@
+:::note
+- This feature is compatible with most programming languages and requires no additional setup.
+- 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.
+- 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.
+:::

docusaurus/docs/_includes/ApiExamplePaginationImportant.mdx

@@ -0,0 +1,3 @@
+:::caution
+[Learn how to use pagination](/codacy-api/using-the-codacy-api#using-pagination) to ensure that you process all results returned by the API.
+:::

docusaurus/docs/_includes/ApiTokenWarning.mdx

@@ -0,0 +1,5 @@
+:::caution
+**Never write API tokens to your configuration files** and keep your API tokens well protected, as they grant owner permissions to your projects on Codacy.
+
+It's a best practice to store API tokens as environment variables. Check the documentation of your CI/CD platform on how to do this.
+:::

docusaurus/docs/_includes/ClientSideToolAdvanced.mdx

@@ -0,0 +1,14 @@
+export default function ClientSideToolAdvanced({ toolName }) {
+  return (
+    <>
+      <h2>Advanced configuration</h2>
+      <p>
+        See the available{' '}
+        <a href="https://github.com/codacy/codacy-analysis-cli#configuration">
+          Codacy Analysis CLI configuration flags
+        </a>{' '}
+        to configure running {toolName} in more advanced scenarios.
+      </p>
+    </>
+  );
+}

docusaurus/docs/_includes/ClientSideToolInstructionsItems.mdx

@@ -0,0 +1,74 @@
+import ApiTokenWarning from './ApiTokenWarning.mdx';
+
+export default function ClientSideToolInstructionsItems({ toolName }) {
+  return (
+    <>
+      <li>
+        <a href="/repositories-configure/configuring-code-patterns/">
+          Enable {toolName}
+        </a>{' '}
+        and configure the corresponding code patterns on your repository{' '}
+        <strong>Code patterns</strong> page.
+      </li>
+
+      <li>
+        Enable <strong>Run analysis on your build server</strong> on your
+        repository <strong>Settings</strong>, tab <strong>General</strong>,{' '}
+        <strong>Repository analysis on your server</strong>.
+        <p>
+          This setting enables Codacy to wait for the results of the local
+          analysis before resuming the analysis of your commits.
+        </p>
+        <p>
+          <img
+            src="./images/run-analysis-through-build-server.png"
+            alt="Run analysis on your build server"
+          />
+        </p>
+      </li>
+
+      <li>
+        Set up an API token to authenticate on Codacy:
+        <ul>
+          <li>
+            <strong>If you're setting up one repository</strong>,{' '}
+            <a href="/codacy-api/api-tokens#repository-api-tokens">
+              obtain a repository API token
+            </a>{' '}
+            and set the following environment variable to specify your
+            repository API token:
+            <pre>
+              <code className="language-bash">
+                export CODACY_PROJECT_TOKEN=&lt;your repository API token&gt;
+              </code>
+            </pre>
+          </li>
+          <li>
+            <strong>If you're setting up multiple repositories</strong>,{' '}
+            <a href="/codacy-api/api-tokens#account-api-tokens">
+              obtain an account API Token
+            </a>{' '}
+            and set the following environment variable to specify the account
+            API token:
+            <pre>
+              <code className="language-bash">
+                export CODACY_API_TOKEN=&lt;your account API token&gt;
+              </code>
+            </pre>
+          </li>
+        </ul>
+        <ApiTokenWarning />
+      </li>
+
+      <li>
+        <strong>If you're using Codacy Self-hosted</strong> set the following
+        environment variable to specify your Codacy instance URL:
+        <pre>
+          <code className="language-bash">
+            export CODACY_API_BASE_URL=&lt;your Codacy instance URL&gt;
+          </code>
+        </pre>
+      </li>
+    </>
+  );
+}

docusaurus/docs/_includes/CoverageGithubAcceptPermissions.mdx

@@ -0,0 +1,3 @@
+:::note
+GitHub only: this feature requires updated app permissions. If you haven't done so yet, please [review and accept the updated Codacy app permissions](https://docs.github.com/en/enterprise-cloud@latest/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#reviewing-permissions) on GitHub.
+:::

docusaurus/docs/_includes/CoverageIgnore.mdx

@@ -0,0 +1 @@
+To exclude files from coverage analysis only, you must ignore them directly in the tool you're using to generate coverage reports and ensure that the reports you upload to Codacy don't include coverage information for those files.

docusaurus/docs/_includes/DashboardApiReportNote.mdx

@@ -0,0 +1,11 @@
+:::note
+You can use the Codacy API to generate reports or obtain information  
+about the code quality of your repositories in a more flexible way.
+
+For more information see the list of  
+[available API endpoints](https://api.codacy.com/api/api-docs#codacy-api-analysis)  
+and the following examples:
+
+- [Obtaining current issues in repositories](/codacy-api/examples/obtaining-current-issues-in-repositories)
+- [Obtaining code quality metrics for files](/codacy-api/examples/obtaining-code-quality-metrics-for-files)
+:::

docusaurus/docs/_includes/DefaultGitProviderSettingsTip.mdx

@@ -0,0 +1,33 @@
+import Admonition from '@theme/Admonition';
+
+export default function DefaultGitProviderSettingsTip({
+  variant = 'default-settings',
+}) {
+  if (variant === 'apply-all') {
+    return (
+      <Admonition type="tip">
+        <p>
+          You can{' '}
+          <a href="/organizations/integrations/default-git-provider-integration-settings#apply-all">
+            apply the default Git provider integration settings to all
+            repositories
+          </a>{' '}
+          to ensure that your repositories all share the same settings.
+        </p>
+      </Admonition>
+    );
+  }
+
+  return (
+    <Admonition type="tip">
+      <p>
+        Configure the{' '}
+        <a href="/organizations/integrations/default-git-provider-integration-settings">
+          default Git provider integration settings
+        </a>{' '}
+        that Codacy applies to new repositories to help ensure that all new
+        repositories have the same settings.
+      </p>
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/IssueDetails.mdx

@@ -0,0 +1,8 @@
+Click the title of an issue card to expand it and see the following information:
+
+- The committer and date of the commit that introduced the issue, if available
+- The estimated time to fix the issue
+- What the issue is and how to solve it
+- The [tool that reported the issue](/getting-started/supported-languages-and-tools/) and the related code pattern
+- Where this pattern is enabled: coding standard, repository rules, or configuration file
+

docusaurus/docs/_includes/NavMultistep.mdx

@@ -0,0 +1,47 @@
+import Link from '@docusaurus/Link';
+
+export default function NavMultistep({ step }) {
+  const activeStep = typeof step === 'number' ? step : Number(step);
+  const steps = [
+    {
+      label: 'Adding your first repository',
+      href: '/getting-started/codacy-quickstart#adding-your-first-repository',
+    },
+    {
+      label: 'Configuring your repository',
+      href: '/getting-started/configuring-your-repository#configuring-your-repository',
+    },
+    {
+      label: 'Integrating Codacy with your Git workflow',
+      href: '/getting-started/integrating-codacy-with-your-git-workflow#integrating-codacy-with-your-git-workflow',
+    },
+  ];
+
+  return (
+    <nav className="nav-multistep" aria-label="Guided path">
+      <p className="nav-multistep__label">
+        This page is part of the following guided path:
+      </p>
+      <ol className="nav-multistep__list">
+        {steps.map((item, index) => {
+          const isActive = index === activeStep;
+
+          return (
+            <li
+              key={item.href}
+              className={`nav-multistep__step ${
+                isActive ? 'nav-multistep__step--active' : ''
+              }`}
+            >
+              {isActive ? (
+                <span className="nav-multistep__current">{item.label}</span>
+              ) : (
+                <Link to={item.href}>{item.label}</Link>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}