diff options
author | 2021-12-22 08:22:11 -0500 | |
---|---|---|
committer | 2021-12-22 08:22:11 -0500 | |
commit | ded142e4d21a638706efb319674b81a1840d6701 (patch) | |
tree | ba9887cc0e58f91da352e989834a1e397849dfd0 /docs/src | |
parent | 29976c6de0d52f8cde49598c6b26a1f9e3ec846e (diff) | |
download | astro-ded142e4d21a638706efb319674b81a1840d6701.tar.gz astro-ded142e4d21a638706efb319674b81a1840d6701.tar.zst astro-ded142e4d21a638706efb319674b81a1840d6701.zip |
Update Configuration Reference documentation (#2239)
* Update Configuration Reference documentation
* Update docs/src/pages/reference/configuration-reference.md
Co-authored-by: Peter Singh <drgaud@hotmail.com>
* nit: update initial config example
* nit: update initial config example
* clarify pages option
* nit: update how the configuration reference is organized
Co-authored-by: Peter Singh <drgaud@hotmail.com>
Diffstat (limited to 'docs/src')
-rw-r--r-- | docs/src/pages/reference/configuration-reference.md | 88 |
1 files changed, 72 insertions, 16 deletions
diff --git a/docs/src/pages/reference/configuration-reference.md b/docs/src/pages/reference/configuration-reference.md index 5946d3e67..7d6cb37e9 100644 --- a/docs/src/pages/reference/configuration-reference.md +++ b/docs/src/pages/reference/configuration-reference.md @@ -3,22 +3,78 @@ layout: ~/layouts/MainLayout.astro title: Configuration Reference --- -To configure Astro, add an `astro.config.mjs` file in the root of your project. All settings are optional. - -You can view the full configuration API (including information about default configuration) on [GitHub.](https://github.com/withastro/astro/blob/latest/packages/astro/src/%40types/astro.ts) +To configure Astro, add an `astro.config.mjs` file to the root of your project. ```js -// Example: astro.config.mjs - -// @type-check enabled! -// VSCode and other TypeScript-enabled text editors will provide auto-completion, -// helpful tooltips, and warnings if your exported object is invalid. -// You can disable this by removing "@ts-check" and `@type` comments below. - -// @ts-check -export default /** @type {import('astro').AstroUserConfig} */ ( - { - // ... - } -); +export default /** @type {import('astro').AstroUserConfig} */ ({ + // all options are optional; these values are the defaults + projectRoot: './', + public: './public/', + dist: './dist/', + src: './src/', + pages: './pages/', + renderers: [ + '@astrojs/renderer-svelte', + '@astrojs/renderer-vue', + '@astrojs/renderer-react', + '@astrojs/renderer-preact', + ], + vite: {}, +}); ``` + +#### projectRoot + +The `projectRoot` option sets the working directory used by Astro. Astro will resolve all other directory options from this path. + +**Default**: The current working directory. + +#### public + +The `public` option sets the directory used to resolve public assets. Astro does not process any files within this directory. + +**Default**: The `public` directory within the `projectRoot` directory. + +#### dist + +The `dist` option sets the directory used to output the final build of the project. Contents of the `public` directory are also copied into this directory. + +**Default**: The `dist` directory within the `projectRoot` directory. + +#### src + +The `src` option sets the directory used to resolve source files, like `pages`. Astro may process, optimize, and bundle any files in this directory. + +**Default**: The `src` directory within the `projectRoot` directory. + +#### pages + +The `pages` option sets the directory used to resolve pages, relative to the `src` option. + +**Default**: The `pages` directory within the `src` directory. + +#### renderers + +The `renderers` option defines the framework renderers to be used by Astro. + +**Default**: An array of `@astrojs/renderer-svelte`, `@astrojs/renderer-vue`, `@astrojs/renderer-react`, and `@astrojs/renderer-preact`. To assign no renderers at all, you must provide an empty array (`[]`). + +#### buildOptions + +The `buildOptions` option configures how a site is built, including its base URL (`buildOptions.site`), whether it includes a sitemap (`buildOptions.sitemap`), and whether its pages should be files (`path.html`) or directories (`path/index.html`) (`buildOptions.pageUrlFormat`). + +#### devOptions + +The `devOptions` option configures features used during development, including the server hostname (`devOptions.hostname`), the server port (`devOptions.port`), and whether urls should include a trailing slash (`devOptions.trailingSlash`). + +#### vite + +The `vite` option configures the internals of Vite. These options can be explored on [ViteJS.dev](https://vitejs.dev/config/). + +#### markdownOptions + +The `markdownOptions` option assigns options to the Markdown parser. These options can be explored on [GitHub](https://github.com/withastro/astro/blob/latest/packages/astro/src/@types/astro.ts). + +--- + +You can view the entire configuration API on [GitHub](https://github.com/withastro/astro/blob/latest/packages/astro/src/@types/astro.ts). |