Project Structure

Overview of the structure of a Vocs project

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:

vocs.config.ts

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'
})

Read the Config API

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/
│   ...

Read the Routing Guide

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:

example.mdx

![Logo](/logo.svg)

Example.tsx

<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:

layout.tsx

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:

footer.tsx

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:

styles.css

@tailwind base;
@tailwind components;
@tailwind utilities;
 
:root {
  --vocs-color_background: white;
}
 
:root.dark {
  --vocs-color_background: #232225;
}