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,17 @@
+CURRENT SCOPE
+- [ ] ADD INTERCOM
+- [ ] ADD TRACKING
+- [ ] REVIEW RELEASE PROCESSES
+- [ ] REVIEW HIERARCHY
+- [ ] REVIEW ORDER OF THINGS IN SIDEBAR
+- [ ] REVIEW THEME - FELIPE
+- [ ] REVIEW URLS TO MAKE SURE THEY MATCH PRODUCTION
+- [ ] FIX ALL INNER URLS
+- [ ] ADD TO README CHANGES FROM PREVIOUS DOCS AND BEST PRACTICES
+- [ ] REVIEW MARKDOWN
+
+- [x] AUTO LAST UPDATED
+- [x] REVIEW TABS
+
+TBD
+- [ ] ADD VERSIONS (see `src/content/docs/maintainers/docs-versioning.md`)

docusaurus/docs/_includes/AdminAccessControlInfo.mdx

@@ -0,0 +1,15 @@
+import Admonition from '@theme/Admonition';
+
+export default function AdminAccessControlInfo() {
+  return (
+    <Admonition type="note">
+      <p>
+        Organization admins can{' '}
+        <a href="/organizations/roles-and-permissions-for-organizations#change-analysis-configuration">
+          manage access to this feature
+        </a>
+        .
+      </p>
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/AdminAccessInfo.mdx

@@ -0,0 +1,9 @@
+import Admonition from '@theme/Admonition';
+
+export default function AdminAccessInfo() {
+  return (
+    <Admonition type="note">
+      <p>Only organization admins can update this setting.</p>
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/AiInfo.mdx

@@ -0,0 +1,28 @@
+import Admonition from '@theme/Admonition';
+
+export default function AiInfo() {
+  return (
+    <Admonition type="note">
+      <ul>
+        <li>
+          This feature is compatible with most programming languages and requires
+          no additional setup.
+        </li>
+        <li>
+          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.
+        </li>
+        <li>
+          This feature leverages the OpenAI API. No information is shared with
+          other third parties or used to train AI models. Refer to the{' '}
+          <a href="https://openai.com/policies/api-data-usage-policies">
+            OpenAI API data usage policies
+          </a>{' '}
+          for more information.
+        </li>
+      </ul>
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/ApiExamplePaginationImportant.mdx

@@ -0,0 +1,26 @@
+import Admonition from '@theme/Admonition';
+
+export default function ApiExamplePaginationImportant({ github = false }) {
+  return (
+    <Admonition type="caution">
+      <p>
+        For the sake of simplicity, the example doesn't consider paginated
+        results obtained from the Codacy API.{' '}
+        <a href="/codacy-api/using-the-codacy-api#using-pagination">
+          Learn how to use pagination
+        </a>{' '}
+        to ensure that you process all results returned by the API.
+      </p>
+      {github && (
+        <p>
+          Besides this, the script doesn’t consider paginated results obtained
+          from the GitHub API.{' '}
+          <a href="https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api">
+            Learn how to use pagination on the GitHub API
+          </a>{' '}
+          to ensure that you obtain all the repositories in your organization.
+        </p>
+      )}
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/ApiTokenWarning.mdx

@@ -0,0 +1,17 @@
+import Admonition from '@theme/Admonition';
+
+export default function ApiTokenWarning() {
+  return (
+    <Admonition type="caution">
+      <p>
+        <strong>Never write API tokens to your configuration files</strong> and
+        keep your API tokens well protected, as they grant owner permissions to
+        your projects on Codacy.
+      </p>
+      <p>
+        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.
+      </p>
+    </Admonition>
+  );
+}

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,16 @@
+import Admonition from '@theme/Admonition';
+
+export default function CoverageGithubAcceptPermissions() {
+  return (
+    <Admonition type="note">
+      <p>
+        GitHub only: this feature requires updated app permissions. If you
+        haven't done so yet, please{' '}
+        <a href="https://docs.github.com/en/enterprise-cloud@latest/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#reviewing-permissions">
+          review and accept the updated Codacy app permissions
+        </a>{' '}
+        on GitHub.
+      </p>
+    </Admonition>
+  );
+}

docusaurus/docs/_includes/CoverageIgnore.mdx

@@ -0,0 +1,10 @@
+export default function CoverageIgnore() {
+  return (
+    <span>
+      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.
+    </span>
+  );
+}

docusaurus/docs/_includes/DashboardApiReportNote.mdx

@@ -0,0 +1,31 @@
+import Admonition from '@theme/Admonition';
+
+export default function DashboardApiReportNote() {
+  return (
+    <Admonition type="note">
+      <p>
+        You can use the Codacy API to generate reports or obtain information
+        about the code quality of your repositories in a more flexible way.
+      </p>
+      <p>
+        For more information see the list of{' '}
+        <a href="https://api.codacy.com/api/api-docs#codacy-api-analysis">
+          available API endpoints
+        </a>{' '}
+        and the following examples:
+      </p>
+      <ul>
+        <li>
+          <a href="/codacy-api/examples/obtaining-current-issues-in-repositories">
+            Obtaining current issues in repositories
+          </a>
+        </li>
+        <li>
+          <a href="/codacy-api/examples/obtaining-code-quality-metrics-for-files">
+            Obtaining code quality metrics for files
+          </a>
+        </li>
+      </ul>
+    </Admonition>
+  );
+}

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,16 @@
+export default function IssueDetails() {
+  return (
+    <>
+      <p>Click the title of an issue card to expand it and see the following information:</p>
+      <ul>
+        <li>The committer and date of the commit that introduced the issue, if available</li>
+        <li>The estimated time to fix the issue</li>
+        <li>What the issue is and how to solve it</li>
+        <li>
+          The <a href="/getting-started/supported-languages-and-tools/">tool that reported the issue</a> and the related code pattern
+        </li>
+        <li>Where's this pattern enabled: coding standard, repository rules, or configuration file</li>
+      </ul>
+    </>
+  );
+}