Personal Docs

Toggle Theme

Create a VitePress website ​

NOTE

This setup is ideal for generating static sites, just like this one. And it uses VitePress, which is a static site generator (SSG) built on top of Vite.

Pre-requisites ​

  • Node.js
  • YARN package manager

Steps ​

  • Clean a blank GitHub project.
  • Clone it locally and cd into the folder.
  • Install VitePress as dev dependency using:
sh
yarn add -D vitepress
  • Start VitePress setup wizard using:
sh
yarn vitepress init
  • Questions to answer in the wizard:
    • Where should VitePress initialize the config?
      • ./docs
    • Site title:
      • Personal Docs
    • Site description:
      • All Personal Docs of Pirate Developer
    • Theme:
      • Default Theme (Out of the box, good-looking docs)
    • Use TypeScript for config and theme files?
      • Yes
    • Add VitePress npm scripts to package.json?
      • Yes
  • The setup wizard would now create following folder and files, inside docs folder:
    • .vitepress folder (VitePress configuration goes here)
    • index.md file (Landing page for your site)
    • markdown-examples.md file (can be removed)
    • api-examples.md file (can be removed)
  • Update your .gitignore file to include following if not already done:
txt
.DS_Store
.idea/
node_modules/
docs/.vitepress/dist
docs/.vitepress/cache
  • Update config.mts file to adjust to your needs.
  • Start local server using:
sh
yarn docs:dev
  • Your website should now be available at http://localhost:5173.

Sample Site Config ​

js
// File found at docs/.vitepress/config.mts
export default defineConfig({
  title: "Personal Docs",
  description: "All personal docs of Pirate Developer",

  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['script', { src: '/js/search.js' }]
  ],
  
  lastUpdated: true,
  metaChunk: true,

  markdown: {
    toc: {
      level: [1, 2, 3, 4, 5, 6]
    }
  },

  themeConfig: {
    logo: '/img/logo.webp',
    darkModeSwitchLabel: 'Toggle Theme',
  
    outline: [1, 6],
    
    search: {
      provider: 'local'
    },

    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Pirate Dev', link: 'https://piratedev.com/' },
      { text: 'Cool Bytes', link: 'https://coolbytes.in/' }
    ],

    sidebar: sidebarConfig,

    socialLinks: [
      { icon: 'discord', link: 'https://discord.com/users/piratedev.com/' },
      { icon: 'github', link: 'https://github.com/PirateDevCom' },
      { icon: 'npm', link: 'https://www.npmjs.com/~piratedev.com' },
      { icon: 'x', link: 'https://x.com/PirateDevCom' },
      { icon: 'youtube', link: 'https://www.youtube.com/@piratedeveloper' }
    ],

    footer: {
      message: '<a href="https://api.piratedev.com/privacy/" style="text-decoration: none" aria-label="Privacy">Privacy Policy</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="https://api.piratedev.com/tos/" style="text-decoration: none" aria-label="Terms of Service">Terms of Service</a>',
      copyright: `Copyright © 2021-${new Date().getFullYear()} Pirate Dev.Com`
    }
  }
})

Directory Structure ​

shell
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.mjs
│  ├─ book1
│  │  └─ chapter1
│  │    └─ page1.md -->  /book1/chapter1/page1.html
│  │    └─ page2.md -->  /book1/chapter1/page2.html
│  └─ index.md -->  /index.html (accessible as /)
└─ package.json

The Public Directory ​

shell
./docs/public
./docs/public/img/ -> Referenced as /img/image1.img
./docs/public/css/
./docs/public/js/