Merge branch 'main' into migrationForumUpdates

# Conflicts:
#	astro/src/content/docs/apis/users.mdx
#	astro/src/content/docs/lifecycle/migrate-users/general-migration.mdx
#	astro/src/content/docs/lifecycle/migrate-users/index.mdx
#	astro/src/content/docs/lifecycle/migrate-users/provider-specific/cognito.mdx

.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+# Runs the linter on the changed files in the PR
+name: Run ESLint on changed files
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  run_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+        # I want to lint only the files that have changed in the PR
+        # This is a bit tricky because we need to fetch the main branch to compare against
+        # Instead I am using the GitHub cli to fetch the changes in the PR
+      - name: Install GitHub CLI
+        run: sudo apt-get install gh
+
+      - name: Authenticate GitHub CLI
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token
+
+      - name: Set Pull Request Number
+        run: echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+
+      - name: NPM Install
+        run: |
+          cd astro
+          npm ci
+        shell: bash
+
+      - name: ESLint
+        run: |
+          cd astro
+          npm run lint-pr
+        shell: /usr/bin/bash -e -o pipefail {0}

DocsDevREADME.md

@@ -81,16 +81,17 @@ Review [the component for all options and icons](astro/src/components/icon/Icon.
 
 ### Docs Navigation
 
-If you want to order pages within a section, use `navorder`. The default value for every page is [defined here](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/config.js#L61).
+Make descriptions full sentences.
+
+If you want to order pages within a section, use `navOrder`. The default value for every page is [defined here](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/config.js#L61).
 
 Pages are ordered in the nav within a section in descending order. 
 
 ```
 navorder: 0
 ```
 
-Make descriptions full sentences.
-
+If you want to sort a category to the top of its section, you need to add it to `astro/src/tools/docs/categoriesToFloatToTop.json`.
 
 ### Including files
 - If you are building a file to include across multiple sections of documentation, make sure you preface the filename with `_` and use dashes to separate words: `_login-api-integration` not `_login_api_integration`.
@@ -212,6 +213,7 @@ Fruits were domesticated at different times.
 - curl
 - Docker
 - Docker Compose
+- e-commerce
 - ECMAScript
 - Elasticsearch
 - esport
@@ -228,7 +230,7 @@ Fruits were domesticated at different times.
 - OAuth and OAuth2
 - re-authentication
 - self-service
-- server-side
+- server-side (an adjective)
 - Spring Boot
 - third-party
 - two-factor

astro/.remarkrc.js

@@ -0,0 +1,81 @@
+import remarkLint from 'remark-lint';
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended';
+import { lintRule } from 'unified-lint-rule';
+import { visitParents } from 'unist-util-visit-parents';
+
+const htmlTagsWithMarkdownEquivalents = [
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', // Headings
+  'p', // Paragraphs
+  'br', // Line Breaks
+  'strong', 'b', // Bold
+  'em', 'i', // Italic
+  'blockquote', // Blockquote
+  'ol', 'ul', 'li', // Lists
+  'code', // Inline Code
+  'pre', // Code Block
+  'hr', // Horizontal Rule
+  'a', // Links
+  'img' // Images
+];
+
+const invalidAnchorAttributes = ['href', 'title'];
+const invalidImageAttributes = ['src', 'alt', 'title'];
+const checkIfHtml = (node, parents, file) => {
+  if (!node.position) return
+
+  // Is this html-ish?
+  if (/^[\t ]*<!--/.test(node.value)) return
+
+  const name = node.name;
+  // check if name starts with a capital letter
+  const isComponent = /^[A-Z]/.test(name);
+  // check if the tag has no markdown equivalent
+  const tagHasNoMarkdownEquivalent = !htmlTagsWithMarkdownEquivalents.includes(name);
+  if (isComponent || tagHasNoMarkdownEquivalent) return;
+
+  // check for attributes on the tags a and img
+  if (name === 'a' && node.attributes.find(attr => !invalidAnchorAttributes.includes(attr.name))) {
+    return;
+  }
+
+  if (name === 'img' && node.attributes.find(attr => !invalidImageAttributes.includes(attr.name))) {
+    return;
+  }
+
+  file.message(`Unexpected HTML tag [${name}], use markdown instead`, {
+    ancestors: [...parents, node],
+    place: node.position
+  });
+}
+
+// this is the lint rule definition
+const noHtml = lintRule(
+    {
+      origin: 'remark-lint:no-html',
+    },
+
+    function (tree, file) {
+      //console.log(tree);
+      visitParents(tree, 'mdxJsxFlowElement', function (node, parents) {
+        checkIfHtml(node, parents, file);
+      })
+
+      visitParents(tree, 'paragraph', function (node, parents) {
+        [...node.children].forEach((child) => {
+          if (child.type === 'mdxJsxTextElement') {
+            checkIfHtml(child, parents, file);
+          }
+        });
+      })
+    }
+)
+
+const remarkConfig = {
+  plugins: [
+    remarkLint,
+    remarkPresetLintRecommended,
+    noHtml
+  ]
+};
+
+export default remarkConfig;

astro/README.md

@@ -31,3 +31,27 @@ To run in dev, so file changes are picked up:
 ```
 npm run dev
 ```
+
+## Linting
+If you want to run the linter for the whole project you can run:
+
+```sh
+npm run lint
+```
+
+However, the project has a billion violations at the moment. To target a specific file, you can run:
+
+```sh
+ npm run lint -- src/components/BlogButton.astro
+```
+
+or similar to just target the individual files you want to check. Also your editor should be able to run the linter as you edit, so you will see your violations in real time.
+
+If you need to skip the linter for any reason you can add a comment for either `eslint-disable-next-line` or `eslint-disable-line` to the line you want to skip.
+
+```markdown
+{/* eslint-disable-next-line */}
+<a href="https://www.fusionauth.io">FusionAuth</a>
+```
+
+The check on Pull Requests will only look at the files that you have changed in your PR

astro/astro.config.ts

@@ -6,6 +6,7 @@ import tailwind from "@astrojs/tailwind";
 import indexPages from "astro-index-pages/index.js";
 import {rehypeTasklistEnhancer} from './src/plugins/rehype-tasklist-enhancer';
 import {codeTitleRemark} from './src/plugins/code-title-remark';
+import remarkMdx from 'remark-mdx';
 
 const optionalIntegrations = [];
 if (!process.env.DEV) {
@@ -37,12 +38,13 @@ const config = defineConfig({
   ],
   markdown: {
     remarkPlugins: [
-        codeTitleRemark
+      codeTitleRemark,
+      remarkMdx,
     ],
     rehypePlugins: [
-        // Tweak GFM task list syntax
-        // @ts-ignore
-        rehypeTasklistEnhancer(),
+      // Tweak GFM task list syntax
+      // @ts-ignore
+      rehypeTasklistEnhancer(),
     ]
   },
   site: 'https://fusionauth.io/',

astro/eslint.config.js

@@ -0,0 +1,69 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+import * as mdx from 'eslint-plugin-mdx';
+import eslintPluginAstro from 'eslint-plugin-astro';
+import tsParser from "@typescript-eslint/parser";
+import astroParser from 'astro-eslint-parser';
+
+export default [
+  {files: ["**/*.{js,mjs,cjs,ts,md,mdx}"]},
+  {languageOptions: { globals: globals.browser }},
+  {
+    ...pluginJs.configs.recommended,
+    files: ["**/*.{js,mjs,cjs}"]
+  },
+  ...(tseslint.configs.recommended.map(config => ({
+    ...config,
+    files: ["**/*.ts"]
+  }))),
+  {
+    name: 'ts-overrides',
+    rules: {
+    }
+  },
+  ...(eslintPluginAstro.configs['flat/base'].map(config => {
+    return {
+      ...config,
+      files: ["**/*.astro"],
+      languageOptions: {
+        parser: astroParser,
+        parserOptions: {
+          parser: tsParser,
+          extraFileExtensions: ['.astro'],
+          project: './tsconfig.json',
+          sourceType: 'module',
+        }
+      }
+    }})),
+  {
+    ...mdx.flat,
+    // optional, if you want to lint code blocks at the same
+    processor: mdx.createRemarkProcessor({
+      lintCodeBlocks: false,
+      // optional, if you want to disable language mapper, set it to `false`
+      // if you want to override the default language mapper inside, you can provide your own
+      languageMapper: {},
+    }),
+    rules: {
+      ...mdx.flat.rules,
+      // if you want to override some rules for md/mdx files
+      'mdx/remark': 'error',
+      'no-unused-expressions': 'off',
+      'remark-lint-no-undefined-references': 'off',
+      'no-undef': 'off',
+    }
+  },
+  {
+    files: ['**/*.astro'],
+    languageOptions: {
+      parser: astroParser,
+      parserOptions: {
+        parser: tsParser,
+        extraFileExtensions: ['.astro'],
+        project: './tsconfig.json',
+        sourceType: 'module',
+      }
+    }
+  }
+];