michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update Configuration Reference documentation (#2239)

Browse source 
* 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>
This commit is contained in:
Jonathan Neal 2021-12-22 08:22:11 -05:00 committed by GitHub
parent 29976c6de0
commit ded142e4d2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 72 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
docs/src/pages/reference/configuration-reference.md
View file

@ -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).