Project Structure
Overview
A general overview of the structure of a Vocs project:
my-project/ # Your project's root directory.
├── docs/ # The root directory of your documentation.
│ ├── pages/ # Directory for your documentation pages (routes).
│ │ └── index.mdx
│ └── public/ # Directory for static assets.
│ └── favicon.ico
├── node_modules/
├── src/
├── .gitignore
├── package.json
└── vocs.config.ts # Vocs configuration file.
Vocs is designed to reside within a subdirectory (default: "./docs"
) of a larger project (ie. a library). However, it is also possible to use Vocs standalone, and you can change the root directory from "./docs"
to "."
if you wish.
Configuration File
Vocs uses a configuration file (vocs.config.ts
) to define global metadata for your documentation.
This includes things like the site title, description, logo, sidebar, and more for your project.
my-project/
│ ...
├── .gitignore
├── package.json
└── vocs.config.ts
A basic vocs.config.ts
could look like this:
import { defineConfig } from 'vocs'
export default defineConfig({
description: 'Build reliable apps & libraries with lightweight, \
composable, and type-safe modules that interface with Ethereum.',
title: 'Viem'
})
Root Directory
The Root Directory contains all of your documentation pages, static assets, components, etc.
By default, Vocs will look for a directory named ./docs
in your project's root directory.
You can change this directory by setting the rootDir
property in your vocs.config.ts.
my-project/
├── docs/
│ ├── pages/
│ │ └── index.mdx
│ └── public/
│ └── favicon.ico
├── node_modules/
│ ...
Routing
Vocs uses file-based routing. This means that each file inside of the ./docs/pages
directory will be treated as a route.
Files within the pages directory can be: Markdown or MDX files, or React components (for more customizability).
my-project/
├── docs/
│ ├── pages/
| | ├── index.mdx
| | └── about.tsx
│ └── public/
│ └── favicon.ico
├── node_modules/
│ ...
Static Assets
Static assets (images, fonts, etc.) can be placed in the public
directory.
my-project/
├── docs/
│ ├── pages/
| | ├── index.mdx
| | └── about.tsx
│ └── public/
│ ├── logo.svg
│ └── favicon.ico
├── node_modules/
│ ...
They can be referenced in code like so:
![Logo](/logo.svg)
<img src="/logo.svg" />
Layout Component
A layout React component can be added to your Vocs root directory. The layout component will be used to wrap all of your documentation pages. This can be useful for adding static CSS files, or further customizing the layout of your documentation.
my-project/
├── docs/
│ ├── pages/
| | ├── index.mdx
| | └── about.tsx
│ └── public/
│ | └── favicon.ico
| └── layout.tsx
├── node_modules/
│ ...
The layout.tsx
component could look like:
import { CustomLayout } from './Layout'
export default function Layout({ children }) {
return <CustomLayout>{children}</CustomLayout>
}
Footer Component
A footer React component can be added to your Vocs root directory. The footer component will be displayed at the bottom of all documentation pages.
my-project/
├── docs/
│ ├── pages/
| | ├── index.mdx
| | └── about.tsx
│ └── public/
│ | └── favicon.ico
| └── footer.tsx
├── node_modules/
│ ...
The footer.tsx
component could look like:
export default function Footer() {
return (
<div>
<div>Released under the MIT License.</div>
<div>Copyright © 2022-present weth, LLC.</div>
</div>
)
}
Global Styles
Global styles can be added under a styles.css
file.
my-project/
├── docs/
│ ├── pages/
| | ├── index.mdx
| | └── about.tsx
│ └── public/
│ | └── favicon.ico
| └── styles.css
├── node_modules/
│ ...
The styles.css
file could look like:
@tailwind base;
@tailwind components;
@tailwind utilities;
:root {
--vocs-color_background: white;
}
:root.dark {
--vocs-color_background: #232225;
}