How to disable 404 page not found routing ? Use vitepress as a pre-processor

[adiroiban]

For my website I have some pages that are not generated by vitepress.

For example, I have the API docs that are generated using a tool like pydoctor ... similar to Python Sphinx API docs.

For example, I want to generate a Python Jinja2 template.

For the API docs pages, I want to share the same header and footer with the vitepress site.

I was able to create a placeholder page

For example I have this custom layout

<script setup lang="ts">
// Generate a Jinja2 template with the same footer and header as the vitepress site.
import Header from './components/Header.vue';
import Footer from './components/Footer.vue';
</script>

<template>
  <Header />
  {%- block document -%}

    {%- block body %}{% endblock -%}

  {%- endblock -%}
  <Footer />
</template>

It will generate an .HTML file that I can use as Jinja2 template.

The files are generated just fine.

The problem, is that when I load the file, the vitepress router kicks in and will convert the page into a 404.

---

Is there a way to disable the 404 page routing ?

I still want to use the vite JS code, for example to show/hide the menu for mobile view.... so I don't want to disable the vuejs UI interaction code.

[brc-dd]

Hmm, IIUC, you've generated some file like .vitepress/dist/foo.html with Jinja statements. Now you are using that file for different location?

Like that file is meant for /foo, but you might have something like

@app.route("/bar")
def bar():
    return render_template("foo.html", **{...})

Which will be serving it at different URL - /bar? This will cause issues because vitepress will try to find JS chunks for bar.md but those aren't there in build output.

There is no feasible way to solve the issue. You can generate those placeholders for all possible routes using dynamic routes. But even then there will be errors because hydration will fail after initial load. Or if you do full page load on each route change, then it might work, but will be slower for your end users.

VitePress is not a good fit for these cases. You'll need an ISR/SSR framework. Though even then you'll need to make it an API returning html blocks and handle injection directly in vue. Well, if you're making it an API, then you can do client-side rendering on vitepress too, but then you'll need to inject inline HTML which will cause CSP issues for you.

[adiroiban]

Thanks for the info.

Yes.

The file is generated as .vitepress/dist/foo.html but then used as the template to generate URLs like /api/packageA/class.html and /api/moduleA/method.html, all these URLs from the same same foo.html

Note, that I have a foo.md file.

I am not using flask, I am using a script that calls Jinja and generates static HTML files.

But yes, this will be similar to something like this

@app.route('/apidocs/<str:parent>/<member>')
def apidocs(parent, member):
    return render_template("foo.html", **{...})

---

My hope is that I configure vitepress to always load the chunk from foo.md for URLs that start with /apidocs/

---

If vitepress is not designed for this use case, that is fine.
I will continue to use pelican.
With pelican, this use case works just fine... since pelican has no "embedded" JS app.

Since vitepress is a static site generator, my hope was that it can generate "static pages".
That is, pages that don't depend on a particular route or URL.
The HTML/CSS/JS is generated and it will work regardless on the URL that you use to load those pages.

[brc-dd]

Hmm, hard to make vitepress work with this case. But you are saying you've a script not a server, then why not run your script first?

You can write all those blocks to a JSON file from your script and then run vitepress build where you can create a dynamic route loader to read that JSON and generate the paths.

[brc-dd]

Looked at pelican. I think astro can serve you better. You can use their starlight theme which provides similar features as vitepress. They both work because they are MPA SSGs. VitePress is a SPA SSG.

[adiroiban]

Many thanks for all your support. Much appreciated.

Pelican is a very simple "old school" HTML generator with included support for blog pages... but no support for vite or vitejs. My current site uses Pelican and I was considering moving to something more modern.

Vitepress looks straigh forward

Astro looks complex ... I am still trying to use vitepress as I way to learn more about vite and vuejs :)

I have created a POC ... see the separate comment

[adiroiban]

I simple way to reproduce this behaviour.

I have foo.md that will generate .vitepress/dist/foo.html

pnpm docs:build
mv .vitepress/dist/foo.html .vitepress/dist/bar.html
pnpm docs:preview
firefox http://localhost:4173/bar.html

Expected result: I see the exact same content for what was foo.html
Actual result: I get a page not found for bar.html ... and firefox http://localhost:4173/foo.html return the page just fine... even thou there is no longer an actual foo.html on the disk

---

My hope is that there can be a simple way to tell the vitepress app not to panic when loading bar.html and just go with the chunk for what would have been foo.html

[brc-dd]

Yeah, so when you request /bar.html it will serve with 200, but when the JS chunk is not found the app will crash. We need JS chunks for hydration. If you're visiting /foo.html, then the server will serve with 404 status code, but since the chunk exists, it will hydrate that not found page as if there was content. In both of these cases you'll see hydration mismatch error in browser console, and many things might not work properly.

[adiroiban]

So... I came up with this POC
adiroiban@0b1a2c9

@brc-dd what do you think ? I can work to move the confige outside of the theme and write documentation and use case example

A preview of the changes

You configure the theme with your "extenralPages"
These are pages for which the HTML/JS/CSS was generated by Vitepress, but will be served from URLs that are not defined inside vitepress SPA

  themeConfig: {
    // Map from an URL regex to a vitepress page.
    externalPages: [
      ['.apidocs.*', '/placeholders/apidocs'],
    ],
    logo: { src: '/vitepress-logo-mini.svg', width: 24, height: 24 },

the router is updated not to panic

    // Helper to detect if pages are loaded outside of the vitepress SPA
    let insideVitepress = inBrowser


    // This is here to allow loading pages generated by Vitepress
    // outside of the SPA.
    // The config is in themeConfig as it was was easy to pass it
    // but we should have this moved to site config.
    let externalPages = siteDataRef.value.themeConfig.externalPages
    if (externalPages) {
      for (let externalRule of externalPages) {
        const externalPagePattern = new RegExp(externalRule[0])
        if (externalPagePattern.test(pendingPath)) {
          // Make it look like we are accessing the base page.
          latestPendingPath = externalRule[1]
          pendingPath = externalRule[1]
          insideVitepress = false
          break
        }
      }
    }

This works in dev mode... I am trying to get my local dev environment to also work with $ pnpm run docs:build ... I have create a separate discussion for those errors

[adiroiban]

I have pushed a fix for the code... but with this change, it kind of works.. and I don't see any errors in the console

The JS code from the theme switcher works and algolia search also works...so the general JS code is active.

As a tests I did

$ pnpm docs:build
$ cp docs/.vitepress/dist/placeholders/apidocs.html docs/.vitepress/dist/apidocs/test.html
# Modify the HTML to replace the placeholder contet value with some different content.
$ vi docs/.vitepress/dist/apidocs/test.html
$ pnpm docs:preview

Now http://localhost:4173/apidocs/test.html will server the new content.

The <head><title>VALUE</title></head> is not working as expected ...but that will be step 2 :)

[adiroiban]

This only solves the routing issue.

In my test, the hydration part worked as I was using plain text elements.
My layout was like this, without the <Content /> components

<script setup lang="ts">
// Generate a Jinja2 template with the same footer and header as the vitepress site.
import Header from './components/Header.vue';
import Footer from './components/Footer.vue';
</script>

<template>
<Header />
PLACEHOLDER_CONTENT
<Footer></Footer>
PLACEHODLER_FOOTER
</template>

and for testing I was just replacing PLACEHOLDER_CONTENT with some other text.

But as soon as I use a non-text element, hydration kicks in.

So to get this working this need support from vuejs/core

[adiroiban]

Now that I read more about astro I start the understand the concept of "island"

So, basically what I need here, is to let vitepress know that I want to have a static island on the page. It should not panic if there is a different URL and should not try to replace/hidrate the content.

[adiroiban]

For now I gave up on working on this functionalty.

I need to learn more about how vuejs hydration work and how to setup vuejs/core in dev mode.

For my use case, I only needed the HTML/CSS for the header and footer and for now I can manully re-create them.

---

This use case is not supported by vitepress and astra might be a better fit for projects that need to integrated with external pages.