### Install Magidoc CLI and Generate

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/01.Introduction/02.Quickstart.md

Install the Magidoc CLI globally and then run the generate command. Alternatively, use `npx` to run the command without global installation.

```shell
pnpm add --global @magidoc/cli@latest && magidoc generate
```

```shell
# or using npx
npx @magidoc/cli@latest generate
```

--------------------------------

### Install and Run Magidoc CLI Commands

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Install Magidoc globally or run it with npx. Use 'generate' to build the site, 'preview' to serve it locally, and '--help' for options.

```shell
pnpm add --global @magidoc/cli@latest
magidoc generate
```

```shell
npx @magidoc/cli@latest generate
```

```shell
magidoc preview
```

```shell
magidoc generate --help
```

```shell
magidoc preview --help
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/magidoc-org/magidoc/blob/main/CONTRIBUTING.md

Run this command in the root folder to install all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Start Development Server

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/03.Command - Dev.md

Execute this command to launch the development server. Use `--help` for additional options.

```shell
magidoc dev
```

--------------------------------

### Install Plugin and Dependencies

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

Install the GraphQL Query Generator plugin and its peer dependency GraphQL.js using pnpm.

```shell
pnpm install -D @magidoc/plugin-query-generator graphql
```

--------------------------------

### Run Local Development Server

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/starters/carbon-multi-page/README.md

Starts the local development server with hot-reloading enabled.

```bash
pnpm dev
```

--------------------------------

### Install PrismJS Plugin and Dependencies

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/02.PrismJS.md

Install the PrismJS Svelte plugin, PrismJS itself, and its TypeScript types as development dependencies.

```shell
pnpm install -D @magidoc/plugin-svelte-prismjs prismjs @types/prismjs
```

--------------------------------

### Install Rollup GraphQL Schema Plugin

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/03.Rollup GraphQL-Schema.md

Install the plugin using pnpm. This command adds the module as a development dependency.

```shell
pnpm install -D @magidoc/rollup-plugin-gql-schema
```

--------------------------------

### Install Svelte Marked Plugin

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/03.Marked.md

Install the Svelte Marked plugin along with its peer dependency MarkedJS and type definitions.

```shell
pnpm install -D @magidoc/plugin-svelte-marked marked @types/marked
```

--------------------------------

### Configuration for Carbon Multi-Page Template

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/03.Templates/02.Carbon-multi-page.md

Example `magidoc.mjs` configuration file demonstrating supported options for the carbon-multi-page template.

```javascript
// magidoc.mjs

export default {
  website: {
    template: 'carbon-multi-page',
    staticAssets: './assets',
    options: {
      appTitle: 'Magidoc',
      appLogo: 'https://some-website/my-image.png',
      appFavicon: 'https://website.com/favicon.ico',
      siteRoot: '/docs',
      siteMeta: {
        description: 'My carbon template',
      },
      fieldsSorting: 'default',
      argumentsSorting: 'alphabetical',
      directives: [
        {
          name: '*', 
          args: ['*'],
        },
      ],
      pages: [
        {
          title: 'Content',
          // This template supports only a single level of nesting.
          // All sub-levels will be discarded.
          content: [
            {
              title: 'SubContent',
              content: 'Your markdown here.',
            },
          ],
        },
      ],
      externalLinks: [
        {
          href: 'https://some-website.com',
          label: 'Some website',
          position: 'header' // 'navigation'
          group: 'some-group',
          kind: 'some-kind',
        }
      ]
      queryGenerationFactories: {},
    },
  },
}
```

--------------------------------

### Apache Folder Structure Example

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/03.Apache.md

Place the Magidoc output content within your Apache HTML directory, typically /var/www/html. Ensure all generated files and folders are included.

```text
/var/www/html
├── _app
│   └── ...
├── introduction
│   └── welcome.html
├── ...
└── index.html
```

--------------------------------

### Install PrismJS Languages and Svelte Syntax

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/02.PrismJS.md

Import specific PrismJS language components and the prism-svelte highlighter to enable syntax highlighting for those languages.

```svelte
<script lang="ts">
  import Prism from '@magidoc/plugin-svelte-prismjs'
  import 'prismjs/components/prism-graphql'
  import 'prism-svelte' // https://github.com/pngwn/prism-svelte
</script>
```

--------------------------------

### Sample Generated GraphQL Response

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

Example of a response received for the sample GraphQL query.

```javascript
{
  "person": {
    "name": "A name",
    "age": 36,
    "friends": [
      {
        "name": "A name",
        "age": 36
      }
    ]
  }
}
```

--------------------------------

### Factory Key Specificity Examples

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

Illustrates the order of specificity for factory keys, from most specific to least specific, used for generating values.

```typescript
const result = await generateGraphQLQuery(field, {
  factories: {
    // A specific path in the request in the format `field.path$argument.path`
    oddNumbersField$argument: () => 3,
    // An argument by name. For instance, if the argument `birthDate` was used often in your API
    // You could specify a similar value for all `birthDate` fields.
    argument: () => [3],
    // Other matchers on type name
    '[OddNumber!]!': () => [5],
    '[OddNumber!]': () => [7],
    'OddNumber!': () => 9,
    OddNumber: () => 11,
    '*Number': () => 13,
  },
})
```

--------------------------------

### Sample Generated GraphQL Query

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

This is an example of a GraphQL query automatically generated by the plugin.

```graphql
query getPerson($delay: Int, $delay2: Int) {
  person {
    name
    age(delay: $delay)
    friends {
      name
      age(delay: $delay2)
    }
  }
}
```

--------------------------------

### Sample Generated GraphQL Variables

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

Example of variables generated for the sample GraphQL query.

```json
{
  "delay": 42,
  "delay2": 42
}
```

--------------------------------

### Magidoc Configuration with URL Introspection

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/cli/tests/config/examples/magidoc.txt

Configure Magidoc to introspect a GraphQL schema from a remote URL. Includes example headers for authentication or custom settings.

```javascript
/**
 * @type {import("../../../src").MagidocConfiguration}
 */
const config = {
  introspection: {
    type: 'url',
    url: 'https://potato.com/graphql',
    headers: {
      Test: 'something',
    },
  },
  website: {
    template: 'carbon-multi-page',
  },
}

module.exports = config

```

--------------------------------

### Markdown Notification Component

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/03.Templates/02.Carbon-multi-page.md

Example of using the custom 'notification' markdown component to display warnings. Supported types include info, success, warning, and error.

```markdown
:::notification type="warning"
This is a **warning**
:::
```

--------------------------------

### Markdown Tags Component

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/03.Templates/02.Carbon-multi-page.md

Example of using the custom 'tags' markdown component to display small text bubbles. Colors can be specified as a comma-separated list.

```markdown
:::tags colors="red,blue,purple"
this,is,what,tags,look,like
:::
```

--------------------------------

### Markdown Tabs Component

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/03.Templates/02.Carbon-multi-page.md

Example of using the custom 'tabs' markdown component to create distinct content sections. Each section is defined by a '---' separator followed by the tab title.

```markdown
:::tabs
---First tab
This is a **first tab**.

---Second tab
And here is another one with `nested markdown`!
:::
```

--------------------------------

### Generate All Websites

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/examples/multi-schema/readme.md

Execute this command to build the documentation for all configured GraphQL APIs.

```bash
pnpm generate
```

--------------------------------

### Display Help for Preview Command

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/02.Command - Generate.md

The `preview` command can be used to locally preview the built website. Use the `--help` option to discover more about its optional parameters.

```shell
magidoc preview --help
```

--------------------------------

### Preview Generated Website

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/01.Introduction/02.Quickstart.md

Run this command to preview the generated static website locally. The output is typically in the `./docs` folder.

```shell
magidoc preview
```

--------------------------------

### Preview All Websites

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/examples/multi-schema/readme.md

Use this command to preview the aggregated documentation website locally.

```bash
pnpm preview
```

--------------------------------

### Configure Website Options

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Set various options for the documentation website, including template, output path, static assets, and appearance settings like app title, logo, and meta tags.

```javascript
// magidoc.mjs

export default {
  introspection: {
    // ...
  },
  website: {
    /**
     * Either the name of the template to use for the website or,
     * if you used `magidoc eject` to create a starter, the path to your starter's directory.
     */
    template: 'carbon-multi-page',

    /**
     * Optional template version to use.
     * Changing this may cause the build to fail depending on the
     * changes between the version of the cli and the template.
     * It is not recommended to use this property.
     * If you wish to use a specific version of the starter, use a specific version of Magidoc instead.
     *
     * @default current CLI version
     */
    templateVersion: '<magidoc-version>',

    /**
     * The optional output location for the built website.
     *
     * @default './docs'
     */
    output: './docs',

    /**
     * A directory path, where the directory contains additional static assets for the website.
     * This can include images, videos, etc,
     *
     * These assets will then be available at the root URL of your website,
     * conserving the directory structure you put inside this directory.
     *
     * For instance, this can be used to customize the application icon.
     * Inside your directory, put a file named `logo.png`, and as the `appLogo` website setting, use "/logo.png" as the URL for the image.
     *
     * @see https://github.com/magidoc-org/magidoc/blob/main/packages/examples/spacex/magidoc.mjs for an example.
     * @default undefined
     */
    staticAssets: 'path/to/a/directory',

    /**
     * Options to use for the website.
     * Some templates may not support all options.
     * Make sure you check the documentation of the chosen template.
     */
    options: {
      /**
       * Your application title.
       *
       * @default 'Magidoc'
       */
      appTitle: 'Magidoc',

      /**
       * Your application logo, which can either be
       * an absolute URL or a relative URL pointing to a static asset.
       * If your `siteRoot` is set and you use a relative URL, include the `siteRoot` in the path
       *
       * @default (magidoc logo)
       */
      appLogo: 'https://website.com/logo.png',

      /**
       * Your application's favicon, which can either be
       * an absolute URL or a relative URL pointing to a static asset.
       *
       * @default (magidoc logo)
       */
      appFavicon: 'https://website.com/favicon.ico',

      /**
       * The a root path where your website will be served from.
       * It is common to see docs websites hosted on a /docs path.
       * Example: https://your-website.com/docs
       *
       * If your website is served from the root path, leave this undefined.
       *
       * @default undefined
       */
      siteRoot: '/docs',

      /**
       * Customizes the website meta tags in the header of the HTML pages.
       * Any meta tags with the following format are supported:
       *
       * <meta name={key} content={value} />
       *
       * A list of common tags can be found here: https://gist.github.com/whitingx/3840905
       *
       * @default (arbitrary title, description and image are generated from `appTitle` and `appLogo`)
       */
      siteMeta: {
        description: 'This is your website description',
        keywords: 'svelte,docs,magidoc,cool',
      },

      /**
       * A list of custom stylesheets to override the default style. 
       * These stylesheets should be included in your `staticAssets` directory, and the property should be an absolute path to them.
       * 
       * 
       * Be aware that the name of the CSS classes are not guaranteed to stay the same through different versions of Magidoc.
       * Use at your own risk. 
       * 
       * @default []
       */
      customStyles: ['/styles/custom.css'],

      /**
       * Defines the order that the fields of a query/mutation/subscription type appear in the page.
       * Choices are ['default', 'alphabetical']
       *
       * @default 'default' The order used in the schema.
       */
      fieldsSorting: 'default',
      
      /**
       * Defines the order that the arguments of a type appear in the page.
       * Choices are ['default', 'alphabetical']
       *
       * @default 'default' The order used in the schema.
       */
      argumentsSorting: 'default',

      /**
       * The directives that should appear in the documentation.
       * When using SDL introspection, the location and definition of these directives will be displayed where they are used.
       *
       * @default []
       */
      directives: [
        {
          name: "ValidDate",
          args: ["before", "after"],
        },
                {
          name: "ValidInt",
          args: ["*"], // To document all args of a directive.
        },
                {

```

--------------------------------

### Develop Individual Website

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/examples/multi-schema/readme.md

Commands to develop, build, and preview individual GraphQL API documentation sites separately.

```bash
# Dev
pnpm dev:first
pnpm dev:second

# Generate
pnpm generate:first
pnpm generate:second

# Preview
pnpm preview:first
pnpm preview:second
```

--------------------------------

### Eject Magidoc Starter Project

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Copies a built-in template to a local directory for full customization. Update 'website.template' in magidoc.mjs to point to the ejected directory.

```shell
magidoc eject --help
```

```javascript
export default {
  website: {
    template: './template',  // path to the ejected starter directory
  },
}
```

--------------------------------

### Configure Website Options

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Customize website-wide settings such as directive and argument documentation. Use '*' to include all directives and arguments.

```javascript
name: "*", // To document all directives and all args.
          args: ["*"]
```

--------------------------------

### Build All Packages with pnpm

Source: https://github.com/magidoc-org/magidoc/blob/main/CONTRIBUTING.md

Execute this command in the root folder to build all packages, plugins, and templates within the monorepo.

```bash
pnpm build
```

--------------------------------

### Display Help for Generate Command

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/02.Command - Generate.md

Use the `--help` option to discover more about the optional parameters for the `generate` command.

```shell
magidoc generate --help
```

--------------------------------

### Run All Tests with pnpm

Source: https://github.com/magidoc-org/magidoc/blob/main/CONTRIBUTING.md

Use this command in the root folder to run all tests across all packages and projects.

```bash
pnpm test
```

--------------------------------

### Configure Static Assets for Robots.txt

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/04.Google Indexing.md

Specify the directory for static assets in your Magidoc configuration to include the robots.txt file.

```javascript
import path from 'path'

export default {
  website: {
    // ...
    staticAssets: path.join(__dirname, 'assets'),
    // ...
  },
}
```

--------------------------------

### Configure Magidoc for GitHub Pages

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/01.GitHub Pages.md

Set the `staticAssets` path and specify the `siteRoot` for your GitHub Pages deployment. The `siteRoot` should match the base path of your GitHub Pages URL.

```javascript
import path from 'path'

export default {
  website: {
    // ...
    // We will need some mandatory static assets
    staticAssets: path.join(__dirname, 'assets'),
    options: {
      // You need to specify the base path of your github pages root
      // Example: `/magidoc`
      siteRoot: '/<user>/<repo>',
    },
    // ...
  },
}
```

--------------------------------

### Full Parse GraphQL Schema Configuration

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/03.Rollup GraphQL-Schema.md

Review the configuration options for the `parseGraphQLSchema` plugin, including the mandatory `paths` for SDL files, the `target` output path, and the desired `format`.

```javascript
parseGraphQLSchema({
  /**
   * A mandatory list of paths where to the SDL files are located. Glob syntax is supported.
   */
  paths: ['schema/**/*.graphqls'],

  /**
   * The target path where to put the introspection result.
   * This defaults to the src asset directory of SvelteKit, so that the asset can be imported directly.
   *
   * @default 'src/_schema.json'
   */
  target: 'src/_schema.json',

  /**
   * The wished output format for the introspection query result. Accepted values are `sdl` and `introspection.`
   *
   * @default 'introspection'
   */
  format: 'introspection',
})
```

--------------------------------

### Minimal Magidoc Configuration

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/01.Introduction/02.Quickstart.md

Create a `magidoc.mjs` file with this minimal configuration to specify your GraphQL schema source and website template.

```javascript
// magidoc.mjs

export default {
  introspection: {
    type: 'url',
    url: 'https://graphiql-test.netlify.app/.netlify/functions/schema-demo',
  },
  website: {
    template: 'carbon-multi-page',
  },
}
```

--------------------------------

### Basic PrismJS Component Usage in Svelte

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/02.PrismJS.md

Demonstrates the basic usage of the Prism component, specifying the language, source code, and enabling line numbers and a copy button.

```svelte
<script lang="ts">
  import Prism from '@magidoc/plugin-svelte-prismjs'
</script>

<Prism
  language={'javascript'}
  source={`
    const x = 'best plugin ever'
    console.log(x)
  `}
  showLineNumbers
  showCopyButton
/>
```

--------------------------------

### Configure Website Options in magidoc.mjs

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Use this configuration to set up website branding, routing, SEO, custom pages, external links, field sorting, and query factories. Ensure the introspection source is correctly defined.

```javascript
// magidoc.mjs
import path from 'path'

export default {
  introspection: {
    type: 'url',
    url: 'https://spacex-production.up.railway.app/graphql',
  },
  website: {
    template: 'carbon-multi-page',     // built-in template name OR local dir path
    output: './docs',                  // default output directory
    staticAssets: path.join(path.dirname(new URL(import.meta.url).pathname), './assets'),
    options: {
      appTitle: 'SpaceX GraphQL API',
      appLogo: '/logo.png',            // relative (served from staticAssets) or absolute URL
      appFavicon: '/favicon.png',
      siteRoot: '/docs',               // set if hosted at a non-root path
      siteMeta: {
        description: 'SpaceX GraphQL API documentation.',
        keywords: 'graphql,spacex,api',
      },
      customStyles: ['/styles/custom.css'],  // paths inside staticAssets
      fieldsSorting: 'alphabetical',         // 'default' | 'alphabetical'
      argumentsSorting: 'default',
      directives: [
        { name: 'ValidDate', args: ['before', 'after'] },
        { name: '*', args: ['*'] },           // document all directives
      ],
      pages: [
        {
          title: 'Welcome',
          content: `# Welcome\n\nCustom markdown page shown before the API reference.`,
        },
        {
          title: 'Auth',
          content: [                          // nested sub-pages (one level deep)
            { title: 'OAuth 2.0', content: `OAuth flow details here.` },
          ],
        },
      ],
      externalLinks: [
        {
          href: 'https://github.com/your-org/your-repo',
          label: 'GitHub',
          kind: 'GitHub',          // determines icon
          position: 'header',      // 'header' | 'navigation'
          group: 'Repositories',
        },
      ],
      queryGenerationFactories: {
        uuid: '<example-uuid>',    // override scalar value generation
        'Int!': 42,
        String: 'example',
      },
    },
  },
}
```

--------------------------------

### Display Eject Command Options

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/04.Command - Eject.md

Run this command to see all available options for the eject command.

```shell
magidoc eject --help
```

--------------------------------

### Full Fetch GraphQL Schema Configuration

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/03.Rollup GraphQL-Schema.md

Explore all available configuration options for the `fetchGraphQLSchema` plugin, including method, custom query, headers, target path, and output format. Defaults are provided for each option.

```javascript
fetchGraphQLSchema({
  /**
   * Your API URL.
   */
  url: 'https://your-graphql-api-url.com/graphql',

  /**
   * The HTTP Method to use.
   *
   * @default 'POST'
   */
  method: 'POST',

  /**
   * Some APIs do not follow the GraphQL.js standard, so the introspection may be invalid for your API.
   * If this happens, you can specify a different introspection query to use.
   */
  query: '<introspection-query>',

  /**
   * Optional headers to provide in the request.
   *
   * @default {}
   */
  headers: {},

  /**
   * The target path where to put the introspection query result.
   * This defaults to the src asset directory of SvelteKit, so that the asset can be imported directly.
   *
   * @default 'src/_schema.json'
   */
  target: 'src/_schema.json',

  /**
   * The wished output format for the introspection query result. Accepted values are `sdl` and `introspection.`
   * @default 'introspection'
   */
  format: 'introspection',
})
```

--------------------------------

### TypeScript Usage for Query Generation

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/02.GraphQL Query Generator.md

Demonstrates how to use the generateGraphQLQuery and generateGraphQLResponse functions in TypeScript. Ensure GraphQL.js is used to build the schema.

```typescript
import {
  generateGraphQLQuery,
  NullGenerationStrategy,
  QueryType,
} from '@magidoc/plugin-query-generator'
import { buildClientSchema, type IntrospectionQuery } from 'graphql'
import schemaJson from '_schema.json'

// Use GraphQL.js to build the schema
const schema = buildClientSchema(schemaJson as unknown as IntrospectionQuery)
const personField = schema.getQueryType()?.getFields()['person']!!

const context = {
  queryName: 'getPerson',
  queryType: QueryType.QUERY,
  maxDepth: 3,
  nullGenerationStrategy: NullGenerationStrategy.NEVER_NULL,
  factories: {},
}

// Generate a query with variables
const query = await generateGraphQLQuery(personField, context)
// Generates a sample response
const response = generateGraphQLResponse(personField, context)

console.log(query)
console.log(response)
```

--------------------------------

### Configure Static Assets in Magidoc

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/02.Vercel.md

Specify the static assets directory in your Magidoc configuration file. This is necessary for Vercel deployment.

```javascript
import path from 'path'

export default {
  website: {
    staticAssets: path.join(__dirname, 'assets'),
  },
}
```

--------------------------------

### Configure Dev Watch Directories

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Specify globs, file paths, or directories to watch for changes to trigger hot-reloading during development. By default, static assets and the magidoc.mjs file are watched.

```javascript
export default {
  introspection: {
    // ...
  },
  website: {
    // ...
  },
  dev: {
    /**
     * Globs, file paths or directories to watch for and hot-reload on change.
     * By default, Magidoc will reload the website on change of any static assets or the magidoc.mjs file.
     *
     * @see https://github.com/magidoc-org/magidoc/blob/main/docs/magidoc.mjs for an example.
     */
    watch: ['./pages/**/*', './directory', './some-other-file.js'],
  },
}
```

--------------------------------

### Configure Introspection from SDL Files

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Parse GraphQL Schema Definition Language (SDL) files to generate the introspection schema. Supports glob patterns for specifying multiple schema files.

```javascript
export default {
  introspection: {
    /**
     * The SDL introspection type.
     */
    type: 'sdl',

    /**
     * A mandatory paths array where the schema files can be found.
     * Glob syntax is supported in case your schema is split into multiple files.
     */
    paths: ['schemas/**/*.graphqls'],
  },
}
```

--------------------------------

### Configure Dev Server Watch in magidoc.mjs

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Extend the paths that trigger hot-reloading during `magidoc dev`. This configuration is useful for including custom pages, modules, or asset directories in the watch process.

```javascript
export default {
  introspection: { type: 'none' },
  website: { template: 'carbon-multi-page' },
  dev: {
    watch: [
      './pages/**/*',       // watch all markdown page files
      './pages.mjs',        // watch the pages index module
      './extra-assets',     // watch a directory
    ],
  },
}
```

--------------------------------

### Configure Introspection from Raw SDL String

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Provide the GraphQL schema directly as a raw SDL string. Useful for small or inline schemas.

```javascript
export default {
  introspection: {
    /**
     * The raw type.
     */
    type: 'raw',

    /**
     * The raw SDL content.
     */
    content: 'type Query
{	test: String
}',
  },
}
```

--------------------------------

### Apply a PrismJS Theme

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/02.PrismJS.md

Import a PrismJS theme stylesheet to customize the appearance of code blocks. Many themes are available, or you can use custom ones.

```svelte
<script lang="ts">
  import Prism from '@magidoc/plugin-svelte-prismjs'
  import 'prismjs/themes/prism-dark.css'
</script>
```

--------------------------------

### Configure Magidoc for Google Search Indexing

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configuration for Magidoc to allow search engine crawling. Specifies static assets and includes a `robots.txt` file to permit all user agents.

```javascript
// magidoc.mjs
import path from 'path'

export default {
  website: {
    staticAssets: path.join(path.dirname(new URL(import.meta.url).pathname), 'assets'),
  },
}
```

```text
# assets/robots.txt — allow all crawlers
User-agent: *
Disallow:

```

--------------------------------

### Configure Vite for Parsing GraphQL Schema

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/03.Rollup GraphQL-Schema.md

Add the `parseGraphQLSchema` plugin to your `vite.config.js` to parse local SDL files. Specify the paths to your schema files using glob syntax.

```javascript
import parseGraphQLSchema from '@magidoc/rollup-plugin-gql-schema'

export default {
  plugins: [
    parseGraphQLSchema({
      paths: ['schema/**/*.graphqls'],
    }),
  ],
}
```

--------------------------------

### Configure Query Generation Factories

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Set up factories for query generation to customize how specific GraphQL types are handled. This allows for default values or custom transformations.

```javascript
queryGenerationFactories: {
        'Int!': 420,
        String: 'abc',
      }
```

--------------------------------

### Magidoc Configuration: Raw SDL String

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configure Magidoc to use a raw GraphQL schema string directly.

```javascript
export default {
  introspection: {
    type: 'raw',
    content: 'type Query { test: String }',
  },
  website: { template: 'carbon-multi-page' },
}
```

--------------------------------

### Basic Svelte Marked Usage

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/03.Marked.md

Render markdown content using the Markdown component. The 'source' prop accepts a markdown string.

```svelte
<script lang="ts">
  import Markdown from '@magidoc/plugin-svelte-marked'
</script>

<Markdown
  source={`
# Setup
Here are the steps to set up svelte-marked plugin
1. Install it
2. Enjoy
    - If you enjoyed, make sure to star the repo!
`}
/>
```

--------------------------------

### Generate GraphQL Queries and Mock Responses with @magidoc/plugin-query-generator

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Use this library to programmatically build GraphQL query strings, variable objects, and mock responses from a schema. It requires the graphql library and a schema JSON file.

```typescript
import {
  generateGraphQLQuery,
  generateGraphQLResponse,
  NullGenerationStrategy,
  QueryType,
} from '@magidoc/plugin-query-generator'
import { buildClientSchema, type IntrospectionQuery } from 'graphql'
import schemaJson from './_schema.json'

const schema = buildClientSchema(schemaJson as unknown as IntrospectionQuery)
const personField = schema.getQueryType()!.getFields()['person']!

const context = {
  queryName: 'getPerson',
  queryType: QueryType.QUERY,
  maxDepth: 3,
  nullGenerationStrategy: NullGenerationStrategy.NEVER_NULL,
  factories: {
    // Custom scalar
    OddNumber: () => 5,
    // Context-aware factory — returns different values by argument name
    String: (ctx) => {
      if (ctx.targetName.toLowerCase() === 'email') return 'user@example.com'
      return ctx.defaultFactory ? ctx.defaultFactory.provide() : 'abc'
    },
    // Glob path specificity: field.path$argument.path → argument → TypeName → '*Pattern'
    'birthDate': () => '1990-01-01',
    '*Number': () => 13,
  },
}

// Generates: query getPerson($delay: Int) { person { name age(delay: $delay) friends { name } } }
const query = await generateGraphQLQuery(personField, context)
// Generates a mock JSON response matching the schema shape
const response = generateGraphQLResponse(personField, context)

console.log(query.query)      // GraphQL query string
console.log(query.variables)  // { delay: 42 }
console.log(response)         // { person: { name: "A name", age: 36, friends: [...] } }

```

--------------------------------

### Fetch or Parse GraphQL Schema with @magidoc/rollup-plugin-gql-schema

Source: https://context7.com/magidoc-org/magidoc/llms.txt

This Rollup/Vite build plugin fetches a live GraphQL introspection result or parses SDL files. Configure it in your vite.config.js to specify the URL or local paths and the output target.

```javascript
// vite.config.js — fetch from a live endpoint
import { fetchGraphQLSchema } from '@magidoc/rollup-plugin-gql-schema'

export default {
  plugins: [
    fetchGraphQLSchema({
      url: 'https://your-api-url.com/graphql',
      method: 'POST',                   // default
      headers: { Authorization: 'Bearer token' },
      target: 'src/_schema.json',       // default; importable in SvelteKit
      format: 'introspection',          // 'introspection' | 'sdl'
    }),
  ],
}

// vite.config.js — parse local SDL files
import parseGraphQLSchema from '@magidoc/rollup-plugin-gql-schema'

export default {
  plugins: [
    parseGraphQLSchema({
      paths: ['schema/**/*.graphqls'],  // glob supported
      target: 'src/_schema.json',
      format: 'introspection',
    }),
  ],
}

```

--------------------------------

### Configure Vite for Fetching GraphQL Schema

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/06.Plugins/03.Rollup GraphQL-Schema.md

Add the `fetchGraphQLSchema` plugin to your `vite.config.js` to fetch a GraphQL schema via introspection. Ensure the `url` option points to your GraphQL API.

```javascript
import { fetchGraphQLSchema } from '@magidoc/rollup-plugin-gql-schema'

export default {
  plugins: [
    fetchGraphQLSchema({
      url: 'https://your-api-url.com',
    }),
  ],
}
```

--------------------------------

### Magidoc Configuration: SDL Introspection

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configure Magidoc to parse GraphQL schemas from local SDL files. Supports glob patterns for multiple files.

```javascript
export default {
  introspection: {
    type: 'sdl',
    paths: ['schemas/**/*.graphqls'],
  },
  website: { template: 'carbon-multi-page' },
}
```

--------------------------------

### Add External Links

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Include external links in the documentation, such as social media or repository links. Specify href, label, and optionally position, group, and kind for icon display.

```javascript
externalLinks: [
        {
          href: 'https://github.com',
          label: 'Main repository',
          position: 'navigation',
          group: 'Repositories',
          kind: 'GitHub',
        },
      ]
```

--------------------------------

### Syntax-Highlight Code Blocks in Svelte with @magidoc/plugin-svelte-prismjs

Source: https://context7.com/magidoc-org/magidoc/llms.txt

A Svelte component for rendering syntax-highlighted code using PrismJS. Import necessary languages and themes, then use the Prism component with your code source.

```svelte
<script lang="ts">
  import Prism from '@magidoc/plugin-svelte-prismjs'
  // Import any PrismJS language and theme
  import 'prismjs/components/prism-graphql'
  import 'prismjs/themes/prism-dark.css'
</script>

<Prism
  language="graphql"
  source={`
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}
  `}
  showLineNumbers
  showCopyButton
/>

```

--------------------------------

### Register Custom Image Renderer in Svelte

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Demonstrates how to register a custom Svelte component to render markdown images. Ensure the custom component is imported and passed to the 'renderers' prop.

```svelte
<!-- Custom image renderer -->
<!-- MarkdownImage.svelte -->
<script lang="ts">
  import type { Tokens } from 'marked'
  export let token: Tokens.Image
</script>
<img src={token.href} alt={token.text} title={token.title} class="custom-image" />
<style>
  .custom-image { max-width: 50%; }
</style>

<!-- index.svelte — register custom renderer -->
<script lang="ts">
  import Markdown from '@magidoc/plugin-svelte-marked'
  import MarkdownImage from './MarkdownImage.svelte'
</script>
<Markdown source={`![Logo](https://example.com/logo.png)`} renderers={{ img: MarkdownImage }} />
```

--------------------------------

### Vercel Configuration for Clean URLs

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/02.Vercel.md

Add a vercel.json file to your static assets directory to enable clean URLs. This file configures Vercel's behavior.

```json
{
  "cleanUrls": true
}
```

--------------------------------

### Configure Magidoc for GitHub Pages Deployment

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configuration for Magidoc to deploy to GitHub Pages. Specifies the GraphQL introspection endpoint and static asset path. The `siteRoot` option is important for correctly linking assets on GitHub Pages.

```javascript
// magidoc.mjs
import path from 'path'

export default {
  introspection: { type: 'url', url: 'https://api.example.com/graphql' },
  website: {
    template: 'carbon-multi-page',
    staticAssets: path.join(path.dirname(new URL(import.meta.url).pathname), 'assets'),
    options: {
      siteRoot: '/<repo>',  // omit for org private repos
    },
  },
}
```

```text
# Required: disable Jekyll processing
assets/
└── .nojekyll
magidoc.mjs
```

--------------------------------

### Magidoc Configuration: URL Introspection

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configure Magidoc to fetch the GraphQL schema from a live URL using POST requests. Supports custom headers and introspection queries.

```javascript
export default {
  introspection: {
    type: 'url',
    url: 'https://your-graphql-api.com/graphql',
    method: 'POST',                    // default
    headers: {
      Authorization: 'Bearer <token>', // optional auth
    },
    // query: '<custom-introspection-query>', // override if needed
  },
  website: { template: 'carbon-multi-page' },
}
```

--------------------------------

### Configure Magidoc for Vercel Deployment

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Configuration for Magidoc to deploy to Vercel. Includes introspection endpoint, template, and static assets. A `vercel.json` file is used to enable clean URLs.

```javascript
// magidoc.mjs
import path from 'path'

export default {
  introspection: { type: 'url', url: 'https://api.example.com/graphql' },
  website: {
    template: 'carbon-multi-page',
    staticAssets: path.join(path.dirname(new URL(import.meta.url).pathname), 'assets'),
  },
}
```

```json
// assets/vercel.json — enables clean URLs (no .html extension)
{
  "cleanUrls": true
}
```

```shell
magidoc generate
cd docs
vercel deploy
```

--------------------------------

### Registering and Using a Custom Marked Extension

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/03.Marked.md

Register a custom container extension with marked and use it within a Svelte Markdown component. This involves defining the extension logic and providing the custom component as a renderer.

```javascript
<script lang="ts">
  import BackgroundColor from './BackgroundColor.svelte'

  import Markdown,
    {
      extensions,
      type TokenExtractionParameters,
    }
    from '@magidoc/plugin-svelte-marked'
  import { marked } from 'marked'

  // Step 1, register our custom extension
  marked.use({
    extensions: [
      extensions.containerExtension((params: TokenExtractionParameters) => {
        if (params.type === 'background-color') {
          // This will become the `token` parameter of our component
          return {
            type: 'background-color', // This is the `renderer` name.
            raw: params.raw,
            color: params.options['color'] ?? 'red',
            // This empty array indicates the container plugin that you wish 
            // to parse the content of of the container as markdown
            // It will be automatically populated if it is present.
            // If you do not wish to render the content as markdown, set this to null or undefined
            tokens: [],
          }
        }

        return null
      }),
    ],
  })
</script>

<Markdown
  source={`
:::background-color color="lightgray"
Look at this gray background with **internal markdown support**!!
:::
`}
  renderers={{
    'background-color': BackgroundColor,
  }}
/>
```

--------------------------------

### Define Custom Pages

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Add custom pages to your documentation, presented before the GraphQL documentation. Supports markdown content and nested sub-pages. Ensure proper indentation for markdown content.

```javascript
pages: [
        {
          title: 'First item',
          content: `
            # Title

            Your markdown here
          `,
        },
        {
          title: 'Second Item',
          content: [
            {
              title: 'Nested Item',
              content: `Same as before`,
            },
          ],
        },
      ]
```

--------------------------------

### Disable Jekyll for GitHub Pages

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/01.GitHub Pages.md

Create an empty `.nojekyll` file in your `assets` directory to prevent GitHub Pages from using Jekyll to build your site.

```bash
assets
└── .nojekyll
magidoc.mjs
```

--------------------------------

### Render Markdown as Svelte Components with @magidoc/plugin-svelte-marked

Source: https://context7.com/magidoc-org/magidoc/llms.txt

A Svelte markdown renderer powered by MarkedJS. It supports GitHub Flavored Markdown, custom component renderers, and container extensions. Basic usage involves importing the Markdown component and providing a source string.

```svelte
<!-- Basic usage -->
<script lang="ts">
  import Markdown from '@magidoc/plugin-svelte-marked'
</script>

<Markdown source={`

```

--------------------------------

### Configure Introspection from URL

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/01.Magidoc Configuration.md

Fetch the introspection schema from a live GraphQL API endpoint. Supports specifying the URL, HTTP method, custom introspection query, and request headers for authentication.

```javascript
export default {
  introspection: {
    /**
     * The url type.
     */
    type: 'url',

    /**
     * Your API URL.
     */
    url: 'https://your-graphql-api-url.com/graphql',

    /**
     * The HTTP Method to use.
     *
     * @default 'POST'
     */
    method: 'POST',

    /**
     * Some APIs do not follow the GraphQL.js standard, so the introspection may be invalid for your API.
     * If this happens, you can specify a different introspection query to use.
     */
    query: '<introspection-query>',

    /**
     * Optional headers to provide in the request.
     */
    headers: {
      /**
       * Since Magidoc uses configuration as code, you can perform
       * authentication in this file or use environment variables.
       */
      Authorization: 'Bearer xxx',
    },
  },
}
```

--------------------------------

### Register Custom Container Extension in Svelte

Source: https://context7.com/magidoc-org/magidoc/llms.txt

Shows how to register a custom Svelte component for rendering custom container blocks. The extension must be defined using `extensions.containerExtension` and passed to `marked.use`.

```svelte
<!-- Custom container extension -->
<script lang="ts">
  import BackgroundColor from './BackgroundColor.svelte'
  import Markdown, { extensions, type TokenExtractionParameters } from '@magidoc/plugin-svelte-marked'
  import { marked } from 'marked'

  marked.use({
    extensions: [
      extensions.containerExtension((params: TokenExtractionParameters) => {
        if (params.type === 'background-color') {
          return {
            type: 'background-color',
            raw: params.raw,
            color: params.options['color'] ?? 'red',
            tokens: [],  // populated automatically with child markdown tokens
          }
        }
        return null
      }),
    ],
  })
</script>

<!-- BackgroundColor.svelte renders :::background-color color="lightgray" ... ::: -->
<Markdown
  source={`
:::background-color color="lightgray"
Rendered with a **gray background** and nested markdown!
:::
`}
  renderers={{ 'background-color': BackgroundColor }}
/>
```

--------------------------------

### Minimal Robots.txt Content

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/05.Deployment/04.Google Indexing.md

Use this minimal content in your robots.txt file to allow Google to crawl all pages of your website.

```plaintext
User-agent: *
Disallow:
```

--------------------------------

### Detect Dark Mode Preference with JavaScript

Source: https://github.com/magidoc-org/magidoc/blob/main/packages/starters/carbon-multi-page/src/app.html

Detects the user's preference for dark mode and applies a corresponding theme. This script should be placed in the head of your HTML.

```javascript
function setTheme() { const prefersDarkScheme = window.matchMedia( '(prefers-color-scheme: dark)' ).matches
if (prefersDarkScheme) {
  document.documentElement.setAttribute('theme', 'g100')
} else {
  document.documentElement.setAttribute('theme', 'white')
}
}
setTheme()
window
  .matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', setTheme)
```

--------------------------------

### Register Custom Image Renderer

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/03.Marked.md

Register a custom Svelte component for image rendering by passing it to the 'renderers' prop of the Markdown component.

```svelte
<!-- index.svelte -->
<script lang="ts">
  import Markdown from '@magidoc/plugin-svelte-marked'
  import MarkdownImage from './MarkdownImage.svelte'
</script>

<Markdown
  source={`
Amazing image:
![Look at this image](https://lh3.googleusercontent.com/2hDpuTi-0AMKvoZJGd-yKWvK4tKdQr_kLIpB_qSeMau2TNGCNidAosMEvrEXFO9G6tmlFlPQplpwiqirgrIPWnCKMvElaYgI-HiVvXc=w600)
`}
  renderers={{
    img: MarkdownImage,
  }}
/>
```

--------------------------------

### Custom Markdown Image Renderer

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/07.Svelte Plugins/03.Marked.md

Define a custom Svelte component to render markdown images. This component receives the image token and can access markdown options and renderers.

```svelte
<!-- MarkdownImage.svelte -->
<script lang="ts">
  import type { Tokens } from 'marked'
  import type { MarkdownOptions, Renderers } from '../markedConfiguration'

  export let token: Tokens.Image
  export const options: MarkdownOptions = undefined
  export const renderers: Renderers = undefined
</script>

<img
  src={token.href}
  title={token.title}
  alt={token.text}
  class="custom-image"
/>

<style>
  .custom-image {
    max-width: 50%;
  }
</style>
```

--------------------------------

### Configure Magidoc Template Path

Source: https://github.com/magidoc-org/magidoc/blob/main/docs/pages/02.Cli/04.Command - Eject.md

When ejecting, you can specify the path to your custom template directory by changing the `website.template` property in your `magidoc.mjs` configuration file.

```javascript
// magidoc.mjs

export default {
  website: {
    template: './template',
  },
}
```

--------------------------------

### Skip Git Hooks During Commit

Source: https://github.com/magidoc-org/magidoc/blob/main/CONTRIBUTING.md

Perform a commit while bypassing pre-commit hooks, such as linting, by using the --no-verify flag.

```bash
git commit -m "<your-message>" --no-verify
```