Vuepress: Allow per-component overriding

[davestewart]

It would be really useful to be able to override theme-components on a per-component basis.

If they were registered globally not locally, could we then override them in enhanceApp? :

import Home from './components/theme/Home'

export default ({ Vue, options, router }) => {
    Vue.component('home', Home)
}

Either that, or specify components in config.js ?:

import Home from './components/theme/Home'

themeConfig: {
    components: {
        home: Home
    }
}

Maybe eject could be modified, or a new command added to extract the component to override:

vuepress extract Home.vue

[ulivz]

Thanks for your suggestion, but we don't think overriding only one of a theme components is a good way since all components in a theme should exist as an organic whole.

[davestewart]

You think it would introduce problems, or you just don't like the idea?

Wordpress has child themes where you can override logic, layout and styling.

In Vuepress, you can currently override styles and routing.

Why not just be able to tweak a single element of an otherwise appropriate theme?

[ulivz]

Hmmm...

If you just want to override a default theme component, you can just eject out of the custom theme directly.

if only one of the component was ejected, then we will need to clarify the internal interface of all the default themes at the present stage and load the components dynamically at run time according to your preferences.

The default theme does not want to be so complex. Our priority is to ensure that the core is stable and applied to all the documents of the Vue sub project.

[davestewart]

The problem with ejecting, as the docs say, is you lose the ability to upgrade.

So I just tested it...

// default theme/Layout.vue

// move Home from local to global registration
Vue.component('home', Home)

export default {
  components: { Page, Sidebar, Navbar }
  ...
}

// .vuepress/enhanceApp.js

// override Home with local version
import Home from './components/Home'

export default ({Vue, options, router}) => {
  Vue.component('Home', Home)
}

... and it delivers the desired result:

It was super easy.

I don't see how that would affect core stability, it just allows those who know enough about the theme to tweak a component by itself.

Maybe you want a custom home, maybe you don't like the sidebar, or external links.

If you decide you don't like things enough, then you eject.

It's like "progressive theming"

[ulivz]

"lose the ability to upgrade." —— This is the biggest problem. It seems that you can work in this way, and just demonstrate the simplest component, but if we modify the internal interface? next, will we get the inexplicable issue?

[davestewart]

but if we modify the internal interface?

You mean, like this?

    <!-- home - features block -->
    <div class="features" v-if="data.features && data.features.length">
      <div class="feature" v-for="feature in data.features">
        <h2>{{ feature.title }}</h2>
        <p>{{ feature.details }}</p>
      </div>
    </div>

Well, let's say you change the format for features; if you do that, the user would need to update his README.md front-matter anyway, so whether the entire theme, or just a single component is updated, changing a theme's internal or external mechanisms could run the risk of something not working.

next, will we get the inexplicable issue?

You mean users complaining that something broke?

Well I'm guessing that any developer ejecting the entire theme would have enough Vue knowledge / confidence to work with 15 or so fairly complex components, so surely just ejecting a single component (depending on the component) would narrow down any risk?

Additionally, the user could just comment out the override in to check it was the problem:

// disable override...
// import Home from './components/Home'

Would you, at the very least, reopen and tag this as a discussion?

[yyx990803]

Sorry but no. The whole point is the default theme was designed to fit a specific use case and not aiming to be generically extendable. We have no intention to increase the maintenance surface of the default theme. If you have some specific need, you can either eject or build your own theme.

[davestewart]

I guess it can still be done, just not with the default theme then.

Cheers :)