VitePress Documentation

website·Indexed 32 days ago

https://vitepress-contributors.cssnr.com

A static site generator that allows for custom themes and built-in components like Badge for adding status labels to headers.

Tokens: 4.1K
Snippets: 22
Records: 34
Agent score: 50%

What's inside VitePress

Check GitHub REST API rate limit status
The authoritative source for current rate limit status is the x-ratelimit-* response headers returned with every API request. For a periodic overview of all resource families for an authenticated user, you can call the GET /rate_limit endpoint. Note that calling GET /rate_limit does not count against your primary rate limit, but may count against your secondary rate limit.
https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-apiwebsitellms
Use the setup hook for Composition API logic
The setup hook runs inside the root component's setup(), allowing the use of Composition API calls (like watch or onMounted) without wrapping them in a layout component. Note that browser-only work must be placed inside onMounted as this hook also runs during SSR/SSG.
```
import { watch } from 'vue'
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  setup() {
    const { page } = useData()
    watch(() => page.value.relativePath, (path) => {
      console.log('now viewing', path)
    })
  }
}
```
https://vitepress.dev/guide/custom-themewebsitellms
Increase GitHub REST API rate limits
To obtain higher primary rate limits, consider the following strategies:
- Authentication: Use authenticated requests instead of unauthenticated ones for a significantly higher limit.
- GitHub Apps: For organization automation, use a GitHub App instead of a personal access token. Installation access tokens scale based on the number of repositories and organization users.
- Enterprise Cloud: Upgrade to GitHub Enterprise Cloud for higher rate limits for GitHub Apps and OAuth apps.
https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-apiwebsitellms

Consume an external npm theme

To use a theme distributed via npm, import and re-export it from your .vitepress/theme/index.js. If the theme provides a base configuration, extend it in your .vitepress/config.ts using the extends property.

// .vitepress/theme/index.js
import Theme from 'awesome-vitepress-theme'
export default Theme

// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfig } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'

export default defineConfig<ThemeConfig>({
  extends: baseConfig,
  themeConfig: {
    // Theme-specific options
  }
})

Build a custom layout component
A basic layout must include the <Content /> component to render markdown content. You can use the useData() helper to access page.isNotFound for 404 pages or frontmatter to conditionally render different layouts based on page-level configuration (e.g., layout: home).
```
<script setup>
import { useData } from 'vitepress'
const { page, frontmatter } = useData()
</script>

<template>
  <h1 >Custom Layout!</h1>

  <div v-if="page.isNotFound">
    Custom 404 page!
  </div>
  <div v-if="frontmatter.layout === 'home'">
    Custom home page!
  </div>
  <Content v-else />
</template>
```
https://vitepress.dev/guide/custom-themewebsitellms
Enable a custom theme in VitePress
VitePress enables a custom theme when it detects a theme entry file at .vitepress/theme/index.js or .vitepress/theme/index.ts. When this file exists, VitePress uses the custom theme instead of the default theme.
```
. 
├─ docs                # project root
│  ├─ .vitepress
│  │  ├─ theme
│  │  │  └─ index.js   # theme entry
│  │  └─ config.js     # config file
│  └─ index.md
└─ package.json
```
https://vitepress.dev/guide/custom-themewebsitellms
Install and register the Contributors component in VitePress
To use the Contributors component, download Contributors.vue and place it in your project's theme components directory. Then, register the component globally in your VitePress theme configuration to make the <Contributors> tag available in your markdown files.
```
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import Contributors from './components/Contributors.vue'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Contributors', Contributors)
  },
}
```
https://vitepress-contributors.cssnr.com/llms.txtwebsitellms

Implement the VitePress Theme interface

A custom theme is defined as an object exported as the default export from the theme entry file. The only required property is Layout. Optional hooks include enhanceApp for Vue app instance modification, setup for Composition API logic in the root component, and extends to inherit from another theme.

interface Theme {
  /** Root layout component for every page @required */
  Layout: Component
  /** Enhance Vue app instance @optional */
  enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
  /** Runs inside the root component's `setup()` @optional */
  setup?: () => void
  /** Extend another theme @optional */
  extends?: Theme
}

interface EnhanceAppContext {
  app: App // Vue app instance
  router: Router // VitePress router instance
  siteData: Ref<SiteData> // Site-level metadata
}

Setup Contributors component in VitePress theme

To use the <Contributors /> component globally in your VitePress site, register it in your theme configuration and provide the contributors data via global properties.

// .vitepress/theme/index.ts
import DefaultTheme, { VPBadge } from 'vitepress/theme'
import Contributors from '@cssnr/vitepress-plugin-contributors'
import '@cssnr/vitepress-plugin-contributors/style.css'
import contributors from '../contributors.json'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', VPBadge)
    app.component('Contributors', Contributors)
    app.config.globalProperties.$contributors = contributors
  },
}

Build the get-contributors script without dependencies
You can use @vercel/ncc to compile get-contributors.ts into a standalone file that runs without external dependencies. This is useful for creating a portable version of the script.
```
# Install ncc globally
npm i -g @vercel/ncc

# Build normal version
npx ncc build src/get-contributors.ts -o dist/get-contributors

# Build minified version
npx ncc build -m src/get-contributors.ts -o dist/get-contributors
```
https://vitepress-contributors.cssnr.com/llms.txtwebsitellms

Install @cssnr/vitepress-plugin-contributors

Install the contributors plugin for VitePress using your preferred package manager.

# npm
npm i @cssnr/vitepress-plugin-contributors

# pnpm
pnpm i @cssnr/vitepress-plugin-contributors

# yarn
yarn add @cssnr/vitepress-plugin-contributors

# bun
bun i @cssnr/vitepress-plugin-contributors

Use the Badge component in VitePress
The Badge component is globally available in VitePress and is used to add status labels (such as version numbers or status tags) to headers. It can be used by providing a text prop or by passing children into the component slot.
```
### Title <Badge type="info" text="default" />
### Title <Badge type="tip" text="^1.9.0" />
### Title <Badge type="warning" text="beta" />
### Title <Badge type="danger" text="deprecated" />


### Title <Badge type="info">custom element</Badge>
```
https://vitepress.dev/reference/default-theme-badgewebsitellms