Evaluate VuePress alternatives

[fharper]

Let's take the time to evaluate VuePress and possible alternative for our documentation. We are missing some features we need right now.

[fharper]

@React-learner please add your research here so we can discuss about it with anyone who wants to.

[tpayet]

@bidoubiwa Could you make a list of all the plugins we have on the actual documentation and their usage please :)

I know we choose vuepress over docusaurus one year ago for some reasons and I know that you have build some custom plugin that we might have to re-build when migrating to a new platform for our documentation ^^

[bidoubiwa]

Plugins made by us

• CodeSamples: it is behind all the code tabs present in the documentation. These tabs are dynamically generated by pulling all the .code-samples.meilisearch.yaml from every SDK that is added to the list (see .vuepress/code-samples/sdks.json and for more explaination see .vuepress/code-samples/README.md)

• Client glossary: creates hover info boxes to explain some naming that is often used: like primary key, attribute, field, value. See See .vuepress/components/glossary.vue`

• Route highlighter: This is used to create the route showcase using the right colors for the right methods GET, POST, PUT and DELETE. See .vuepress/components/RouteHighlighter.vue

• Config path checker: This is very specific to the scrapper curquiza made. We had to ensure that routes did not have a trailing slash. I guess this is not something you will need to export to the new documentation. See .vuepress/config-path-checker

• docs-scraper: These are the configs given to the scrapper to tell him how he should scrap and order the data in MeiliSearch. See .vuepress/docs-scrapper

• Error-pages: this is what creates the error page dynamically using the yaml errors.yaml at the root of the project. see .vuepress/error-pages

External plugins we use:

• Mermaid: Creates schemas using a simple syntax. This has been created by Thomas. You can find it here. See .vuepress/components/mermaid.vue

• check-md: this is used to ensure that every link in the documentation points to an existing page.
• sitemap: this is used to generate a sitemap. Which is very useful for SEO
• img-lazy: used to load images after page load so that they do not stop the page from loading (the gif on the landing page of the doc is very heavy. You could ask quentin he has a technique to make them way less heavy)
• vuepress-plugin-element-tabs: this is used to created tabs. Tabs are not native to markdown:

- vuepress-plugin-container: Lets us create custom blocks (not just warning or errors):

[fharper]

Thanks @bidoubiwa !

[fharper]

@philmillman we'll add the info here! Happy for you to add info on your search too as it can help us.

[philmillman]

@philmillman we'll add the info here! Happy for you to add info on your search too as it can help us.

Will do, thanks for including me!

[fharper]

We may not move forward depending on the result of #705 since we are already using it, and it seems like contrary to what we've been told, it will still be supported. This would be the only missing feature based on @React-learner evaluation.

[fharper]

@React-learner still, would be nice to share the conclusion of your research to helps others having the same dilemma as us :D

[bidoubiwa]

and it seems like contrary to what we've been told, it will still be supported.

We are using vuepress v1. Based on what they have published: vuejs/vuepress#2744

Due to lack of maintainers, VuePress v1 is not actively maintained now.

VuePress v1 is likely to be deprecated in the near future.

This is quite alarming!

Also, if the project lack in maintainers, I'm not sure this will be solved with vuepress v2. It might be a good moment to consider alternatives while it is still not an urgent matter.

Meanwhile, we can also upgrade to v2 but that requires some dev work.

[fharper]

It is not alarming. First, they are not saying VuePress is dead, but that v1 won't be officially supported anymore, which happens to all popular softwares. They focus on v2, which is already quite popular: https://github.com/vuepress/vuepress-next. The code will still be open, so if we need to add something OR there is a security issue, we can fix it.

We could upgrade to v2 if we see any values.

I guess my point is, if we are happy with the state of VuePress v1 right now, there is no need to change to something else because it's not maintained anymore.

[bidoubiwa]

Allright no problem for me! I like vuepress it does the job well. I don't think it is urgent to change to another platform as well.

I was just answering your quote:

and it seems like contrary to what we've been told, it will still be supported.

Even if it is still usable, vuepress 1 (the one we use) is not supported anymore.
My bad if I was confusing when telling so (since I think i'm the one being quoted in the quote).

[dichotommy]

I know we choose vuepress over docusaurus one year ago for some reasons

@tpayet There is a big, big reason not to go with Docusaurus, which is that they use Algolia DocSearch (see: https://docusaurus.io/docs/en/search). I assume it would be possible to implement our own search bar since everything is open, but not sure how difficult it would be. Plus, others might still assume incorrectly that we're using the default Algolia search. Don't want to endorse our competitor 😬

Crazy idea: I wonder if the team at Docusaurus would be interested in offering MeiliSearch as an option? 🤔

[bidoubiwa]

What about nuxt content? It provides the customization we will need with the new design and still need for our plugin but also like vuepress lets you write doc in markdown. Also, it's vue as well so plugins will easily migrate to nuxt content. But it does look like it is harder to master and configure.

https://content.nuxtjs.org/

[fharper]

The fact that VuePress have issues with something as basic as anchor URL is another reason to think about changing. Note that we could probably fix it if looking at the code, but you get the gist of what I mean!?

[fharper]

@React-learner needs to finish his analysis on the potential platform and our needs. I think that could be your priority #1 for next week as discussion today.

[mdubus]

If we use Docusaurus, there are 2 things we have to check :

• if we can use an other searchbar than Algolia's
• if we can customize the layout and the components

I will take time in the next weeks to make POCs to be sure this can be done 😀

[fharper]

• if we can use an other searchbar than Algolia's

If we decide to move to Docausurus, we will create an integration for it as we won't use the built-in search :)

[fharper]

• if we can customize the layout and the components

It's a good idea to check, but I would be really surprised if we can't.

[fharper]

I created this document so we can easily compare side by side features needed (or additionnel aspect we good take advantages) and what Docusaurus has https://www.notion.so/meilisearch/Documentation-Framework-703889eebb164bc38212319da6c5dc87

[dichotommy]

We decided to go with Docusaurus, since it:

• Has support for versioning
• Has nice-looking customizable templates
• Allows us to put the documentation, blog, and website all on the same stack

We also seriously considered Gatsby, which fulfills all of our criteria and allows more flexibility, but at the cost of increased development time. In the end we chose Docusaurus for convenience.