-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: creating new docs guide (#7039)
* docs: creating new docs guide * Update docs/content/contributing/2.docs/4.creating-new-docs.md Co-authored-by: Richard Rohrig <45824492+rohrig@users.noreply.github.com> * Update docs/content/contributing/2.docs/4.creating-new-docs.md Co-authored-by: Richard Rohrig <45824492+rohrig@users.noreply.github.com> * Update docs/content/contributing/2.docs/4.creating-new-docs.md Co-authored-by: Richard Rohrig <45824492+rohrig@users.noreply.github.com> --------- Co-authored-by: Richard Rohrig <45824492+rohrig@users.noreply.github.com>
- Loading branch information
1 parent
96bb802
commit ae99057
Showing
1 changed file
with
82 additions
and
0 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,82 @@ | ||
# Adding Docs to Your Project | ||
|
||
Adding documentation helps developers work with your Vue Storefront integration. While you're welcome to use the docs tech stack of your choice, you may chose to use the Vue Storefront Docs theme to be consistent with the rest of the ecosystem. This is the Nuxt Layer used by all Vue Storefront maintained projects. | ||
|
||
|
||
::steps | ||
#step-1 | ||
## Initialize Your Nuxt Project | ||
First, create a Nuxt 3 project inside of your project repo. From the root of your repo, run: | ||
|
||
```sh | ||
npx nuxi init docs | ||
``` | ||
|
||
This creates a Nuxt 3 project inside a `docs` folder with the following structure: | ||
|
||
``` | ||
├── README.md | ||
├── app.vue | ||
├── nuxt.config.ts | ||
├── package.json | ||
├── public | ||
│ └── favicon.ico | ||
├── server | ||
│ └── tsconfig.json | ||
├── tsconfig.json | ||
└── yarn.lock | ||
``` | ||
|
||
Since the Docs Theme takes care of most of the design, logic, and behavior of the site, you should delete the `app.vue` to allow the theme to use its own UI. | ||
|
||
#step-2 | ||
## Install the theme | ||
|
||
Our Base Docs Theme uses Nuxt Content, adds styles, and other default behaviors to create consistency throughout our docs. | ||
|
||
```sh | ||
# npm | ||
npm install sf-docs-base | ||
|
||
# yarn | ||
yarn add sf-docs-base | ||
|
||
# pnpm | ||
pnpm install sf-docs-base | ||
``` | ||
|
||
The Nuxt's [extends](https://nuxt.com/docs/getting-started/layers) property can be used in the `nuxt.config.ts` to tell the project to treat the docs base as its base layer. | ||
|
||
```ts [nuxt.config.ts] | ||
export default defineNuxtConfig({ | ||
extends: ['sf-docs-base'] | ||
}) | ||
``` | ||
|
||
#step-3 | ||
## Creating Content | ||
|
||
To add pages to your project, create a `content/` folder inside of your `docs` application. | ||
|
||
Now, any Markdown files placed here will be converted into pages. You can learn about all of the [Markdown features of Nuxt Content](https://content.nuxt.com/usage/markdown) as well as [additional features added by our base layer](3.base-layer.md). | ||
|
||
For example, you can create a landing page by creating a `/content/index.md` file. | ||
|
||
```md [index.md] | ||
# Welcome! | ||
|
||
Welcome to the Vue Storefront Docs Boilerplate! If you're creating a new Vue Storefront integration, this is the place to start. | ||
|
||
This Nuxt project can help you preview your content locally and get it ready to be merged into the Vue Storefront docs. | ||
|
||
## How It Works | ||
|
||
It extends our [Base Layer](https://docs.vuestorefront.io/contributing/docs/base-layer) to give you all of the modules, components, and features available in the deployed Vue Storefront docs. | ||
``` | ||
|
||
And if you run the docs project, our page is automatically created. | ||
|
||
![Home Page with the Markdown from the last code snippet.](../2.docs/new-docs-page.png) | ||
|
||
You can also use [our documentation](https://github.com/vuestorefront/vue-storefront/tree/main/docs) as a reference for how we create docs. | ||
:: |