DOCSEARCHbyAlgolia
Submit Docs

VuePress Documentation Guide

website·Indexed 29 days ago

https://yiov.github.io/

A guide for using VuePress to create markdown-centered static sites. Covers installation, configuration, Frontmatter, components, styling via CSS variables, plugin integration, and search setup using @vuepress/plugin-docsearch@next with Algolia or self-hosted crawlers.

Tokens
17.3K
Snippets
89
Records
98
Agent score
74%

What's inside VuePress

  1. Overview of VuePress as a Static Site Generator

    VuePress is a Markdown-centric static site generator. It allows users to write content (such as documentation or blogs) using Markdown, which VuePress then converts into a static website for display.

  2. Overview of VuePress core features

    VuePress is a static site generator that focuses on a Markdown-centric project structure with minimal configuration. Key features include:

    • Vue-Driven: Allows the use of Vue components directly within Markdown files and enables the development of custom themes using Vue.
    • High Performance: Pre-renders every page into static HTML for fast initial load, while functioning as a Single Page Application (SPA) once loaded in the browser.

  3. Understand the basic structure of a component

    Components are composed of three primary parts that map to standard web technologies: <template> for HTML structure, <script> for JavaScript logic, and <style> for CSS styling.

  4. VuePress Core Features Overview

    VuePress is a static site generator with the following characteristics:

    • Vue-Powered: Supports Vue components within Markdown and custom themes built with Vue.
    • Performance: Generates pre-rendered static HTML for each page and functions as a Single Page Application (SPA) once loaded.
    • Extensibility: Provides a default theme, supports community themes, and offers a flexible plugin API for plug-and-play features.
    • Bundlers: Uses Vite as the default bundler, but also supports Webpack.

  5. Run a self-hosted DocSearch crawler using Docker

    To index your site without official approval, you can run the algolia/docsearch-scraper image. This requires an Algolia account, a created index, and the jq tool installed on your host system to pass the configuration JSON as an environment variable.
    # 1. Install jq for JSON parsing
yum install jq -y

# 2. Create .env file
echo "APPLICATION_ID=your_app_id
API_KEY=your_admin_api_key" > .env

# 3. Run the scraper
docker run -it --env-file=.env -e "CONFIG=$(cat config.json | jq -r tostring)" algolia/docsearch-scraper

  6. Import external code snippets into Markdown

    Use the @[code] syntax to import code from other files. You can specify line ranges, languages, and highlighting. To handle complex paths, use handleImportPath in the markdown.importCode configuration.
    <!-- Basic import -->
@[code](./.vuepress/config.ts)

<!-- Import lines 1-10 with ts language -->
@[code ts{1-10}](./.vuepress/config.ts)

<!-- Complex: lines 3-10 highlight, ts language, line 3 highlighted, no line numbers -->
@[code{3-10} ts{3}:no-line-numbers](./.vuepress/config.ts)

    <!-- Configuration for custom path handling -->

    import { getDirname, path } from '@vuepress/utils'
const __dirname = getDirname(import.meta.url)

export default defineUserConfig({
  markdown: {
    importCode: {
      handleImportPath: (str) => str.replace(/^@vuepress/, path.resolve(__dirname, './')),
    },
  },
})

  7. Install @vuepress/plugin-docsearch@next

    Install the DocSearch plugin for VuePress using one of the following package managers. If installation fails, ensure you have a stable network connection (or use a proxy/VPN).
    # Using pnpm
pnpm add -D @vuepress/plugin-docsearch@next

# Using yarn
yarn add -D @vuepress/plugin-docsearch@next

# Using npm
npm i -D @vuepress/plugin-docsearch@next

  8. Configure a self-built Algolia DocSearch crawler

    When implementing a self-built crawler for DocSearch, you must define a configuration file that specifies how the crawler identifies content and categorizes pages. Key requirements include providing a default selector and ensuring attributesForFaceting includes both tags and lang to enable search functionality for the crawled data.
    {
    "index_name": "yiov",
    "start_urls": [
        {
            "url": "https://vuepress.yiov.top/guide/getting-started.html",
            "selectors_key": "getting-started",
            "tags": ["getting-started"]
        },
        "https://vuepress.yiov.top/"
    ],
    "stop_urls": [""],
    "selectors": {
        "getting-started": {
            "lvl0": { "selector": "", "default_value": "快速上手" },
            "lvl1": ".theme-default-content h1",
            "lvl2": ".theme-default-content h2",
            "lvl3": ".theme-default-content h3",
            "lvl4": ".theme-default-content h4",
            "lvl5": ".theme-default-content h5",
            "lvl6": ".theme-default-content h6",
            "text": ".theme-default-content p, .theme-default-content li",
            "lang": { "selector": "/html/@lang", "type": "xpath", "global": true }
        },
        "default": {
            "lvl0": { "selector": "", "default_value": "前言" },
            "lvl1": ".theme-default-content h1",
            "lvl2": ".theme-default-content h2",
            "lvl3": ".theme-default-content h3",
            "lvl4": ".theme-default-content h4",
            "lvl5": ".theme-default-content h5",
            "lvl6": ".theme-default-content h6",
            "text": ".theme-default-content p, .theme-default-content li",
            "lang": { "selector": "/html/@lang", "type": "xpath", "global": true }
        }
    },
    "custom_settings": {
      "attributesForFaceting": [
        "lang",
        "tags"
      ]
    }
}

  9. Install @vuepress/plugin-docsearch@next

    Install the DocSearch plugin for VuePress using your preferred package manager. If installation fails, ensure you have a stable network connection (or a proxy/VPN).
    # Using pnpm
pnpm add -D @vuepress/plugin-docsearch@next

# Using yarn
yarn add -D @vuepress/plugin-docsearch@next

# Using npm
npm i -D @vuepress/plugin-docsearch@next

  10. Reference images and public assets

    Images can be referenced via relative paths or from the public directory. Assets in the public directory are copied to the root of the generated site and can be accessed via absolute paths starting with /.
    <!-- Relative path to image in same directory -->
![Description](./image.png)

<!-- Image in public directory (e.g., .vuepress/public/images/hero.png) -->
![Hero](/images/hero.png)

<!-- Using $withBase for theme development -->
<img :src="$withBase('/images/logo.png')" alt="VuePress Logo">

  11. Configure a self-hosted Algolia DocSearch crawler

    When implementing a self-hosted crawler for DocSearch, you must define a configuration file that specifies how the crawler identifies content and categorizes pages. Key configuration requirements include:

    • index_name: The name of the search index.
    • start_urls: A list of URLs to crawl. You can use selectors_key and tags to categorize specific pages.
    • selectors: Defines the CSS selectors for different heading levels (lvl1 through lvl6) and the main content text. A default selector group is mandatory for the crawler to function.
    • stop_urls: A list of URLs that the crawler should ignore.
    • attributesForFaceting: Must include tags and lang to enable search filtering and faceting functionality.
    • default_value: The default value displayed for a category when no specific value is found.
    {
    "index_name": "yiov",
    "start_urls": [
        {
            "url": "https://vuepress.yiov.top/guide/getting-started.html",
            "selectors_key": "getting-started",
            "tags": ["getting-started"]
        },
        "https://vuepress.yiov.top/"
    ],
    "stop_urls": [""],
    "selectors": {
        "getting-started": {
            "lvl0": {
                "selector": "",
                "default_value": "Quick Start"
            },
            "lvl1": ".theme-default-content h1",
            "lvl2": ".theme-default-content h2",
            "lvl3": ".theme-default-content h3",
            "lvl4": ".theme-default-content h4",
            "lvl5": ".theme-default-content h5",
            "lvl6": ".theme-default-content h6",
            "text": ".theme-default-content p, .theme-default-content li",
            "lang": {
                "selector": "/html/@lang",
                "type": "xpath",
                "global": true
            }
        },
        "default": {
            "lvl0": {
                "selector": "",
                "default_value": "Preface"
            },
            "lvl1": ".theme-default-content h1",
            "lvl2": ".theme-default-content h2",
            "lvl3": ".theme-default-content h3",
            "lvl4": ".theme-default-content h4",
            "lvl5": ".theme-default-content h5",
            "lvl6": ".theme-default-content h6",
            "text": ".theme-default-content p, .theme-default-content li",
            "lang": {
                "selector": "/html/@lang",
                "type": "xpath",
                "global": true
            }
        }
    },
    "custom_settings": {
      "attributesForFaceting": [
        "lang",
        "tags"
      ]
    }
}

  12. Index content using official Algolia DocSearch service

    For public repositories, you can apply for Algolia's official crawler service:

    1. Apply at https://docsearch.algolia.com/ by providing your site URL, email, and repository link.
    2. After approval (typically 6-7 hours), register your account via the invitation email.
    3. In the Algolia dashboard, navigate to Search > Index to accept the application.
    4. If records are not appearing, use the Crawler dashboard (https://crawler.algolia.com/) to debug. Ensure the CSS selectors match your site's content. For VuePress default themes, replace .content_default with .theme-default-content in the crawler editor.
    5. Once data is synced, retrieve the Search API Key from the API Keys section for use in your config.ts.