Skip to content

Commit

Permalink
docs: creating new docs guide (#7039)
Browse files Browse the repository at this point in the history
* 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
mattmaribojoc and rohrig committed May 21, 2024
1 parent 96bb802 commit ae99057
Showing 1 changed file with 82 additions and 0 deletions.
82 changes: 82 additions & 0 deletions docs/content/contributing/2.docs/4.creating-new-docs.md
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.
::

0 comments on commit ae99057

Please sign in to comment.