-
Notifications
You must be signed in to change notification settings - Fork 156
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 🐛 (admin) update admin runtime plugin * ✨ (theme) update default theme, add contentDir to windi parsing * ✨ (asidebottom) update resources * ✨ (windi) cleanup windi config * ✨ (github) update github module logging * ✨ (prose) move prose components in its own folder * ✨ (components) refact components (wip) * ✨ (content) update components (heavily wip) * 🐛 (social-image) fix social image preview * 🐛 (navigation) make it fill space on desktop * 📝 (docs) write a lot of content * ✏️ (js) js by default * 🔧 (package) add generate:nuxtjs command * ✨ (theme) add default slot in card * 📝 (links) fix broken links * 📝 (fix) tagline * 📝 (prose) improve prose page * 📝 (prose) improve prose page * Update docs/content/1.get-started/1.installation.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/1.get-started/1.installation.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/1.my-first-page.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/2.syntax.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/1.my-first-page.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/2.syntax.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/3.features/5.deployment.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/3.features/5.deployment.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/4.theme/1.settings.md Co-authored-by: Daniel Roe <daniel@roe.dev> * 📝 (components) try to fix inject content * Update docs/content/2.writing/2.syntax.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/3.features/5.deployment.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/3.front-matter.md Co-authored-by: Daniel Roe <daniel@roe.dev> * Update docs/content/2.writing/3.front-matter.md Co-authored-by: Daniel Roe <daniel@roe.dev> * 📝 (docs) update front-matter & fix components Co-authored-by: Daniel Roe <daniel@roe.dev>
- Loading branch information
Showing
79 changed files
with
1,586 additions
and
597 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,121 +1,81 @@ | ||
| # Configuration | ||
|
|
||
| > Tailor Docus for your own identity easily :rainbow: | ||
| > Tailor Docus for your own identity easily. 🌈 | ||
| ## Website | ||
|
|
||
| You can create a `content/settings.json` file to configure the website. | ||
| You need to create a `docus.config.js` file to configure the website. | ||
|
|
||
| ```json [content/settings.json] | ||
| { | ||
| "title": "Docus", | ||
| "url": "https://docus.dev", | ||
| // Optional | ||
| "layout": "docs", | ||
| "logo": "logo.svg", | ||
| "twitter": "@nuxt_js", | ||
| "github": "nuxtlabs/docus" | ||
| } | ||
| ``` | ||
|
|
||
| ### Properties | ||
|
|
||
| | Key | Type | Description | | ||
| |---------|------|-------------| | ||
| | `title` | `String` | Documentation title | | ||
| | `description` | `String` | Brief summary about documentation, added for search engine optimization and social sharing | | ||
| | `url` | `String` | Url of your deployed documentation. | | ||
| | `layout` | `String` | The layout of your documentation (defaults to `docs`). Can be changed to `readme` to have a one-page doc. | | ||
| | `logo` | `String` `Object` | Logo of the project, can be an `Object` to set a logo per [color mode](https://github.com/nuxt-community/color-mode-module). To display the logo, see `header.logo` section. | | ||
| | `header.logo` | `Boolean` | Defaults to `false`, set to `true` to display the logo in header. | | ||
| | `header.title` | `Boolean` | Defaults to `true`, set to `false` to hide the title and only display the logo in header. | | ||
| | `twitter` | `String` | Twitter username to link in the header. Example: `@nuxt_js`. | | ||
| | `github` | `Object` or `String` | Can be a `String` to act as `github.repo` if no other config is needed. | | ||
| | `github.repo` | `String` | GitHub repository for the project. This will enable displaying the last version, the releases page, the link at the top and the `Edit this page on GitHub link` on each page. Example: `nuxt/content`. | | ||
| | `github.url` | `String` | For GitHub Enterprise, in addition to `github.repo`, you have to assign an url. Example: `https://hostname`. Defaults to `https://github.com`. | | ||
| | `github.apiUrl` | `String` | For GitHub Enterprise, in addition to `github.repo`, you have to assign an api url. Example: `https://hostname/api/v3/repos`. Defaults to `https://api.github.com/repos`. | | ||
| | `github.branch` | `String` | The default branch for the GitHub repository of your project, used in the `Edit this page on GitHub link` on each page (defaults to `main` if it cannot be detected). | | ||
| | `github.dir` | `String` | The default dir of your project, used in the `Edit this page on GitHub link` on each page (defaults to `''`). Change it if docus is not at the root of your repository. | | ||
| | `github.releases` | `Boolean` | Defaults to true, set to false to disable the releases page. | | ||
| | `algolia` | `Object` | This option allows you to use [Algolia DocSearch](https://docsearch.algolia.com). In order to enable it, you need to provide at least the `apiKey` and the `indexName`. See example below. | | ||
| | `credits` | `Boolean` | Defaults to `true`, set to `false` to hide `Made with Docus` credits | | ||
|
|
||
| ### Algolia Search | ||
|
|
||
| This option allows you to use [Algolia DocSearch](https://docsearch.algolia.com). In order to enable it, you need to provide at least the `apiKey` and the `indexName`: | ||
| ::code-group | ||
|
|
||
| ```json [content/settings.json] | ||
| "algolia": { | ||
| "apiKey": "<API_KEY>", | ||
| "indexName": "<INDEX_NAME>", | ||
| "langAttribute": "language" | ||
| ```javascript [Default config] | ||
| export default { | ||
| title: "Docus", | ||
| url: "https://docus.dev", | ||
| description: 'Write in markdown, use Vue components, style with Windi CSS and enjoy the power of Nuxt.', | ||
| template: 'docs', | ||
| contentDir: 'content' | ||
| } | ||
| ``` | ||
|
|
||
| If you use `i18n`, make sure the `<langAttribute>` is the same as the html lang selector in the config (defaults to `language`). | ||
|
|
||
| Take a look at the [@nuxt/content](https://github.com/algolia/docsearch-configs/blob/master/configs/nuxtjs_content.json) docsearch config for an example. | ||
|
|
||
| ## Theme | ||
|
|
||
| Create `content/theme.json` file to configure the theme. | ||
|
|
||
| ```json [content/theme.json] | ||
| { | ||
| "colors": { | ||
| "primary": "#06B6D4", | ||
| "code": { | ||
| "string": "#679c0d" | ||
| ```javascript [Full config] | ||
| export default { | ||
| title: "Docus", | ||
| url: "https://docus.dev", | ||
| description: 'Write in markdown, use Vue components, style with Windi CSS and enjoy the power of Nuxt.', | ||
| template: 'docs', | ||
| contentDir: 'content', | ||
| layout: { | ||
| header: true, | ||
| footer: true, | ||
| aside: false, | ||
| asideClass: '', | ||
| fluid: false | ||
| }, | ||
| github: { | ||
| repo: 'nuxtlabs/docus', | ||
| branch: 'main', | ||
| dir: 'docs', | ||
| releases: true, | ||
| url: 'https://github.com', | ||
| apiUrl: 'https://api.github.com/repos' | ||
| }, | ||
| theme: { | ||
| header: { | ||
| title: false, | ||
| logo: { | ||
| dark: '/img/logo-dark.svg', | ||
| light: '/img/logo-light.svg' | ||
| } | ||
| }, | ||
| colors: { | ||
| primary: '#00DC82' | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The theme design is based on a `primary` color to make it easy to override, you can specify it using `colors.primary` in your `content/theme.json`, the color palette (50 to 900) is generated using [theme-colors](https://github.com/nuxt-contrib/theme-colors). | ||
|
|
||
| :: | ||
|
|
||
| ### Properties | ||
|
|
||
| | Key | Type | Description | | ||
| |---------|------|-------------| | ||
| | `colors` | `Object` | An object containing all colors for the theme. | | ||
| | `colors.primary` | `String` | The primary color of the theme, the value should be hexadecimal or rgb (`145,22,74`). Default value is `#3073F1`. | | ||
| | `colors.code` | `Object` | The object containing the colors of Prism theme. You know the list of all available colors names, look at [Prism theme vars documentaion](https://github.com/antfu/prism-theme-vars#configuration)| | ||
|
|
||
| ## Nuxt | ||
|
|
||
| `docus` exports a function to setup the `nuxt.config.js` and allows you to add/override the [Nuxt config](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-build). | ||
|
|
||
| You can checkout the [default nuxt.config.js](https://github.com/nuxt/docus/blob/main/src/app/nuxt.config.js) from Docus. We use [defu.arrayFn](https://github.com/nuxt-contrib/defu#array-function-merger) to merge the default configuration with the one provided. | ||
|
|
||
| Example with custom configuration: | ||
|
|
||
| ```ts [nuxt.config.js] | ||
| import { withDocus } from 'docus' | ||
|
|
||
| export default withDocus({ | ||
| buildModules: [ | ||
| 'vue-plausible' | ||
| ] | ||
| plausible: { | ||
| domain: 'docus.dev' | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| ## Windi CSS | ||
|
|
||
| You can override the [default Windi config](https://github.com/nuxt/docus/blob/main/src/theme/windi.config.js) by creating your own `windi.config.js`. | ||
|
|
||
| ```js [windi.config.js] | ||
| module.exports = { | ||
| theme: { | ||
| extend: { | ||
| // ... | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| As with the [Nuxt config](#nuxt), we use [defu.arrayFn](https://github.com/nuxt-contrib/defu#array-function-merger) to merge configurations. | ||
| | `title` | `String` | Website title. | | ||
| | `description` | `String` | Brief summary about your website, added for SEO and OpenGraph. | | ||
| | `url` | `String` | Target URL of your website. | | ||
| | `contentDir` | `String` | The path of your website content directory. | | ||
| | `theme` | `Object` | Your theme configuration, see [here](/theme/settings) for default theme. | | ||
| | **Layout** | | | | ||
| | `layout.header` | `Boolean` | If set to `false`, it will hide the AppHeader by default. | | ||
| | `layout.footer` | `Boolean` | If set to `false`, it will hide the AppFooter by default. | | ||
| | `layout.fluid` | `Boolean` | If set to `true`, the page container will be fluid by default. | | ||
| | `layout.aside` | `Boolean` | If set to `false`, it will hide the AppAside by default. | | ||
| | `layout.asideClass` | `String` | Class attribute that will be applied to AsideNavigation by default. | | ||
| | :icon-git-hub{class="inline w-4 -mt-0.5"} **GitHub Module** | | | | ||
| | `github.repo` | `String` | Your project repository. | | ||
| | `github.branch` | `String` | The branch to link. | | ||
| | `github.dir` | `String` | The directory in which Docus lives in that repository. | | ||
| | `github.releases` | `Boolean` | If set to true, Docus will fetch Github releases. | | ||
| | `github.url` | `String` | The root URL of GitHub. (set by default) | | ||
| | `github.apiUrl` | `String` | The API URL of GitHub. (set by default) | |
Oops, something went wrong.