Get started

This page would get you started on creating your own pastel themed documentation.

Introduction

Hey 👋, you might wonder why I made this project?

The answer:

I got tired of re-using and sharing files and configurations among documentations I created. So this project is an attempt at creating a clean ✒️ — performant 🚀 — and monochromatic 🎨 theme utilizing the power of layers

Quick start

For more information about layers I suggest you checkout this page — Authoring Nuxt Layers

Follow the steps below to have the base setup for your pastel themed documentation:

  1. Create a new project — obviously.
  2. Add the following to the nuxt.config.ts

Info: This command adds nuxt-pastel-docs as a remote layer and its installs dependencies.

ts nuxt.config

export default defineNuxtConfig({
  extends: [["github:oyedejioyewole/nuxt-pastel-docs", { install: true }]],
});
  1. Create a content.config.ts with the following content:

Info: This defines a schema where displayToc determines whether the table of contents would be shown for content pages.

ts content.config

import { defineContentConfig, defineCollection, z } from "@nuxt/content";

export default defineContentConfig({
  collections: {
    content: defineCollection({
      type: "page",
      source: "**/*.md",
      schema: z.object({
        displayToc: z.boolean().default(false),
      }),
    }),
  },
});
  1. Install @nuxt/content as a dependency

Info: Apparently, if you don't install @nuxt/content, it wouldn't be recognized in your project if you try and start the development server.


Perfect, now you can enjoy writing your documentation with my highly opinionated design takes ✨

Configuration

Now for the fun part, customization ✨.

Create an app.config.ts

This allows you to customize properties like the features list — the themeColor — and the headline etc. through the pastelDocs object which follows this schema:

ts 

interface AppConfig {
  pastelDocs: {
    features: string[];
    footer: {
      content: string; // markdown templates are also parsed.
      iconLinks: Record<string, string>; // this is the format: { 'an-icon': 'https://example.com' }
    };
    headline: string;
    icons: Record<string, string>; // this is the format: { 'an-icon': remappedIcon }
    repo: string; // this is the format: your-username/your-repo
    themeColor: string;
  };
}

Overriding components

If you really don't like my design choices (kind of defeats the entire purpose of using this project) — you can decide to roll out your own components and battle with keeping everything in balance.

The structure of the components directory is given below:

This folder contains components that define sections in the theme.

A responsive footer component that displays markdown content and social/external links. It's minimalist by design and adapts to different screen sizes gracefully.

Features:

  1. Markdown support — footer content is parsed from markdown, so you can include links, formatting, etc.
  2. Dynamic icons — social and external links are rendered as icons using the phosphor-icons library
  3. Responsive layout — centers content on small screens, spreads on larger screens
  4. Container queries — uses modern CSS container queries for adaptive sizing

Configuration: The footer pulls its content from app.config.ts

ts 

export default defineAppConfig({
  pastelDocs: {
    footer: {
      content: "Made with ❤️ by [Your Name](https://yoursite.com)",
      icons: {
        "github-logo": "https://github.com/yourusername",
        "twitter-logo": "https://twitter.com/yourusername"
      }
    }
  }
})

Extending theme styles

In cases you don't want to completely override components, you extend the existing styles with your own CSS classes or custom properties. This is where the locally registered theme module comes in handy.

The layer automatically registers a Nuxt module that creates a CSS template accessible via the #nuxt-pastel-docs alias.

Usage

  1. Import the base theme styles in your own CSS file:

css assets/css/main.css

@import "#nuxt-pastel-docs";
  1. Register your CSS in your nuxt.config.ts

ts nuxt.config.ts

export default defineNuxtConfig({
  css: ["~/assets/css/main.css"],
});