Astro Project Setup

Create a TypeScript configuration and a Markdown configuration for your Starlight project.

tsconfig.json

{
    "compilerOptions": {
        "allowJs": true,
        "baseUrl": ".",
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "isolatedModules": true,
        "jsx": "react-jsx",
        "jsxImportSource": "react",
        "module": "ESNext",
        "moduleResolution": "node",
        "noEmit": true,
        "paths": {
            "@/*": ["src/*"],
            "@assets/*": ["src/assets/*"],
            "@components/*": ["src/components/*"],
            "@content/*": ["src/content/*"],
            "@layouts/*": ["src/layouts/*"]
        },
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "strict": true,
        "target": "ESNext",
        "types": ["astro/client"],
        "verbatimModuleSyntax": true
    },
    "exclude": ["node_modules", "dist", ".astro"],
    "extends": "astro/tsconfigs/strict",
    "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.astro", "src/**/*.mdx"]
}

Now, let’s create a Markdown configuration file for remark and rehype plugins that enhance your Markdown processing:

markdown.config.mjs

import { defineConfig } from 'astro/config';
import remarkGfm from 'remark-gfm';
import remarkSmartypants from 'remark-smartypants';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import { h } from 'hastscript';

export default {
    // Configure Markdown processing
    markdown: {
        // Enable GitHub Flavored Markdown
        remarkPlugins: [
            // Add support for GitHub Flavored Markdown (tables, footnotes, strikethrough, etc.)
            remarkGfm,
            // Convert straight quotes to curly, --- to em dashes, -- to en dashes, etc.
            [remarkSmartypants, { dashes: 'oldschool' }],
        ],
        rehypePlugins: [
            // Add ids to headings
            rehypeSlug,
            // Add links to headings
            [
                rehypeAutolinkHeadings,
                {
                    behavior: 'append',
                    content: () => h('span.heading-link', { ariaHidden: 'true' }, h('i.icon.icon-link')),
                    properties: {
                        class: 'anchor-link',
                        ariaLabel: 'Link to this heading',
                        tabIndex: -1,
                    },
                },
            ],
        ],
        // GitHub-like styling for code blocks by default
        shikiConfig: {
            theme: 'github-dark',
            wrap: true,
        },
    },
};

You’ll need to install the dependencies for the markdown configuration:

npm install --save-dev remark-gfm remark-smartypants rehype-slug rehype-autolink-headings hastscript

For better Markdown linting, you might also want a markdownlint configuration:

.markdownlint.json

{
    "MD001": true,
    "MD003": { "style": "atx" },
    "MD004": { "style": "dash" },
    "MD007": { "indent": 2 },
    "MD012": false,
    "MD013": false,
    "MD024": { "siblings_only": true },
    "MD025": true,
    "MD026": false,
    "MD029": { "style": "ordered" },
    "MD033": false,
    "MD034": false,
    "MD036": false,
    "MD040": true,
    "MD041": false,
    "MD046": { "style": "fenced" },
    "MD048": { "style": "backtick" },
    "default": true
}

And to install markdownlint:

Finally, update your package.json scripts to include markdown linting:

npm install --save-dev markdownlint-cli

Now you’ve created several configuration files for your Starlight project:

1. tsconfig.json

   • Extends Astro’s strict TypeScript configuration
   • Sets up path aliases for easier imports (@/components/*, etc.)
   • Configures React JSX support
   • Includes TypeScript settings optimized for a documentation site

2. markdown.config.mjs

   • Enables GitHub Flavored Markdown with remark-gfm
   • Adds smart typography (curly quotes, em dashes)
   • Generates slugs for headers
   • Creates automatic anchor links for easy section referencing
   • Sets up code syntax highlighting with GitHub Dark theme

3. .markdownlint.json

   • Configures markdown linting rules
   • Allows JSX in markdown (disables MD033)
   • Disables line length limits (appropriate for documentation)
   • Enforces consistent header styling and list markers

4. Installation Commands

   • Dependencies for markdown processing
   • Markdownlint for linting markdown files

5. Additional Scripts

   • Commands for linting markdown files
   • Commands for automatically fixing markdown issues

To integrate these configurations:

1. Add the tsconfig.json at the root of your project
2. Add the markdown configuration to your Astro configuration (or merge it with your existing config)
3. Add the markdownlint configuration file at the root
4. Install the dependencies
5. Add the scripts to your package.json

These configurations work together to provide a robust environment for authoring documentation in Markdown and MDX, with proper linting, formatting, and enhanced features like automatic anchor links and smart typography.

Nerden’s Setup Steps

Partytown

npx astro add partytown

Stylelint

npm install --save-dev stylelint stylelint-config-astro stylelint-config-prettier-scss stylelint-config-sass-guidelines stylelint-config-standard stylelint-config-standard-scss stylelint-config-tailwindcss stylelint-declaration-block-no-ignored-properties stylelint-declaration-strict-value stylelint-group-selectors stylelint-plugin-defensive-css stylelint-prettier stylelint-scss stylelint-use-nesting @archoleat/stylelint-config-extended-scss

ESLint

npm install --save-dev eslint @types/eslint @types/eslint-plugin-tailwindcss astro-eslint-parser eslint-config-airbnb-base eslint-config-airbnb-typescript eslint-config-prettier eslint-import-resolver-typescript eslint-plugin-astro eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-mdx eslint-plugin-prettier eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-tsdoc

prettier

npm install --save-dev prettier prettier-plugin-astro prettier-plugin-tailwindcss prettier-plugin-tailwindcss-extra-plus

Fonts & Tailwind

V3

npm install --save @astrojs/tailwind @fontsource-variable/inter @fontsource/inter @material-tailwind/react @tailwindcss/aspect-ratio @tailwindcss/forms @tailwindcss/typography flowbite-react flowbite-typography preline tailwindcss@3 postcss autoprefixer

npm install @headlessui/react@latest @heroicons/react@latest astro-icon

npm i elevio

V4

npm install --save @fontsource-variable/inter @fontsource/inter @material-tailwind/react @tailwindcss/aspect-ratio @tailwindcss/forms @tailwindcss/typography flowbite flowbite-typography preline tailwindcss @tailwindcss/vite

Other

npm install --save-dev @types/node autoprefixer postcss postcss-import sass sharp

TypeScript

npm install --save-dev @astrojs/check typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser