What are recommendations about large documentation site?

[conduent-teamvad]

Hi,

A documentation site I'm building at work at 461 pages generated.

We try to keep it as lean as possible, e.g. :

|___ docs
     |___ shared
     |___ pages
     |___ product
     |___ project-1
     |___ project-2
     ...
     |___ project-N

I see that the RAM goes up to 3GB on build

1/ Is there an organisation structure that is better?
2/ What can we do to lower the impact on the build server ultimately?

We use your theme without any customization apart from some colors.

We have the following theme config:

import { hopeTheme } from 'vuepress-theme-hope'
import plantuml from 'markdown-it-plantuml'

import { NavBarConfig } from "./configs/navbar";

export default hopeTheme({
    //path.resolve(__dirname, './theme'),
    hostname: "localhost:8888",
    author: {
      name: "VAD Team - Conduent",
      url: "localhost:8888"
    },
    logo: '/icons/favicon-32x32.png',
    logoDark: '/icons/dark-favicon-32x32.png',
    locales: {
      '/': {
        navbar: NavBarConfig,
        sidebar: false
      }
    }, 
    plugins: {
      blog: true,
      mdEnhance: {
        linkCheck: 'always',
        align: true,
        container: true,
        footnote: true,
        figure: true,
        include: true,
        mark: true,
        mermaid: true,
        tabs: true,
      }
    }  
    
});

Thanks for your awesome work !

[JeremieLitzler]

Hello,

I've got the same question for my site with 321 pages generated (my repo is public).

What are your recommendations @Mister-Hope?

Thanks.

[Mister-Hope]

Emm, technically speaking, due to VuePress architecture, it has to keep all page data in memory while building, and an extra page means an extra 10-30MB memory.

If you are sensitive with memory, you can try VitePress, it does not have plugin system, and the page data is extracted from markdown content through Vite plugins during dev/build directly, meaning only current page data is available in the application, so it's much faster and take less memory. However it has a strict limitation that you can not access anything besides site config, theme options and current page data by default, making a lot of feature unavailable like structure sidebar. getting title and icons from links and so on.

So the choice is up to you.

VuePress VS VitePress

Target

• VuePress is more likely to be a complete static site generator. It support different bundlers (currently both Webpack and Vite) as well as plugins and themes.

  VuePress's plugin and theme APIs allows developers extracting any standalone feature into a package, any users can import them easily in projects. Through API Users / Plugins / Themes can make customizations easily, such as modifying markdown parser / bundler options/ site config, generating temp files, adding alias, etc.

• VitePress is more likely to be a modified Vite that has a built-in theme and supports converting markdown to page

  VitePress has not plugin or theme system, besides options it provides, simple features could be done by writing Vite plugins.

Start up, dealing pages and resolving routes

• VuePress has a initialize/prepare stage, it will read all page contents from project folder markdown files, and convert them to Page objects, any markdown content will be converted to Vue component, then VuePress process page data with hooks in plugin apis, later it write page data/components to temp folder, VuePress holds these Page objects in app.pages in all time so it can be accessed in API hooks.

• VuePress generate routes from page objects and use standard vue-router package, and you can inject additional information about pages in routeMeta to access it globally (How we support blogging). This also means that all page routes and a full <URL to chunk path> map is injected to client.

• VitePress starts an application immediately by loading theme entry. (just like a vue project using vite)

• VitePress use a custom router, that load markdown files directly.

  • In dev server, vite markdown-loader plugin will check if the current path exist and provide the converted component from markdown if so, if not, 404 page is provided
  • In production server, each markdown(or page) is generated to a js chunk based on path, VitePress just check if the chunk exisit when being request to navigate to a path, and load that chunk directly if so, if not 404 page is provided.

  The above means VitePress doesn't know how many pages and their path at all, it only has the ability to load page if its path is provided. So:

  • In client (browser), only current page data and site config is available.
  • Any thing related to other pages cannot be done without extra modification on VitePress, like getting title/author/tags from an internal route, this affects a lot of features like blogging, generating links with route path, etc.

SSG (Rendering static pages)

• VuePress render pages one by one during SSG by loading page data from map. All page objects are still on app.pages because it should be accessable in onGenerated hook. （Why it takes a lot memory)

• VitePress can render pages parallelly during SSG. And only one page data is needed besides the application itself. (Why it's fast and take little memory here)

[conduent-teamvad]

Hello @Mister-Hope

Are vitepress and your theme compatible even if some feature are not available? For example, the blog and mdEnhance theme plugins are what we really need.

We have no sidebar nor no docsearch.

[Mister-Hope]

I update the original answer and you should be able to understand why blogging is impossible with VitePress without a huge edition.

[Mister-Hope]

A few edits on original answer as it may help more people. This has nothing related to docsearch BTW.

[conduent-teamvad]

Thanks @Mister-Hope