DEV Community ðŸ‘Đ‍ðŸ’ŧðŸ‘Ļ‍ðŸ’ŧ

Cover image for Vuepress vs Vitepress - An ultimate guide for all ya fence-sitters
Megan Yang Mei
Megan Yang Mei

Posted on

Vuepress vs Vitepress - An ultimate guide for all ya fence-sitters

Apple to Pome

I started this Saturday late and out of guilt, I dashed out and skipped rope x 2500 times. But then, I don't have much time to slowly contemplate a full article that compares an apple to another purely because of laziness and lack of skills ðŸĪŠ

I jump to conclusion.


Merits

After I tried out both ( by trying out I meant building 2 full document sites using both ) . I went for Vitepress.

The winning points are:

1. Better home page layout:
Home layout compare vuepress vs vitepress
* Vue's vertical layout vs Vite's more modern horizontal layout
* Vue's column style feature vs Vite's more trendy card style feature
* Vue's plain text vs Vite's gradient if you so prefer

/** in /docs/.vitepress/theme/custom.css */
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(
  120deg,
  #e60737,
  #ea1845,
  #ff7e28,
  #f5c662
);
Enter fullscreen mode Exit fullscreen mode

2. Better sidebar design and presentation
3. Active, Responsive help from vitepress team (promise me, don't go look up my stupid questions in issues)
4. Even You's outlook and his advocacy in vitepress's bright future

Vitepress's turned-offs are:
1. Less components and plugins (might be intentional: "VitePress tries to stay as minimal as possible" by Evan You in vitepress's community discussion)

for example, vitepress doesn't have a badge component that I like so I raised a feature request
Vuepress badge

2. Vitepress is still young at its 1.0.0-alphaxx and vuepress already v2.x and more mature

3. Vitepress's documentation is a bit behind its development. So go to issues, changelog and discussions in its GitHub project you may find more up-to-date information.

For example:
Las update
It is actually supported:

export default{
    lastUpdated: true,
    lastUpdatedText: 'Update Date'
    themeConfig:{
        lastUpdated: ..
        lastUpdatedText: .. /*Stupid me, 
it doesn't show no matter how I put these 
two fields. 
But then in the end, it popped up when 
I finally deployed it in GitHub Page. 
So pardon me lazy enough to find out 
which plays the trick.

RULE OF THUMB: DON'T F TOUCH IT IF IT WORKS!*/
    }
}

Enter fullscreen mode Exit fullscreen mode

Last update

And there is no mentioning of i18n in vitepress but in fact it is the just the same as vuepress ( Haven't tried out yet But it's my bold yet brilliant and logical judgement! ).


Sidebar deep-dive

Vuepress's sidebar is extremely annoying me.

1. By default

By default, If you make 0 efforts in making a sidebar (by not declaring it whatsoever), the default behaviour is no way near desirable. It shows only the navigation of in-page headers ( sidebarDepth only controls the level of the header you'd like to show in the sidebar, 2 indicates until H3).

theme: defaultTheme({
    logo: ...,
    //sidebar: {},
...
Enter fullscreen mode Exit fullscreen mode

Sidebar with only

Default sidebar is just pathetic for it fails to achieve the navigation goals of the site.

2. Using sidebar array
If you decided to do something about it, the painful journey unfolds before you.

You could use sidebar array:

/**.vuepress/config.js */
theme: defaultTheme({
  logo: ...,
  sidebar: [
      {
        text: "Guide",
        link: "/1-Guide/",
        children: [
          {
            text: "Getting Started",
            link: "/1-Guide/Getting Started.md",
          },
          {
            text: "01 Introduction",
            link: "/1-Guide/01 Introduction.md",
          },
        ],
      },
      {
        text: "Admin",
        link: "/admin/",
        children: [
          { text: "Account", link: "/admin/account.md", children: [] },
          {
            text: "admin",
            link: "/admin/admin.md",
            children: [],
          },
        ],
     },
  ],


Enter fullscreen mode Exit fullscreen mode

Of course you could use javascript to auto-generate all the sidebar items in your folder or folders

const fs = require("fs");
const sidebar = () => {
  const files = fs.readdirSync("./docs", { withFileTypes: true });
  //get folders (and not .**)
  const dirs = files  //iterate all the folders in docs/
    .filter(
      (dirent) =>
        dirent.isDirectory() && //no root files
        dirent.name.indexOf(".") == -1 && //no .vuepress
        dirent.name !== "zh" //not your lang foler
    )
    .map((dir) => dir.name);
  console.log(dirs);
  //get all sub
  let sidebar = [];
  dirs.forEach((dir) => {
    let mds = fs
      .readdirSync(`./docs/${dir}`, { withFileTypes: true })
      .filter(
        (dirent) =>
          !dirent.isDirectory() &&
          dirent.name.indexOf(".md" != -1) &&
          dirent.name !== "README.md" &&
          dirent.name !== "index.md"
      )
      .sort((a, b) => {
        return a.name - b.name;
      }) //
      .map((dirent) => {
        return {
          text: dirent.name.split(".md")[0],
          link: `/${dir}/${dirent.name}`,
          children: [],
        };
      });
    console.log(mds);

    sidebar.push({
      text: dir,
      collapsible: false,
      link: `/${dir}/`,
      children: mds,
    });

    // sidebar[`/${dir}/`]=
  });
Enter fullscreen mode Exit fullscreen mode

After I went up and beyond with this lengthy code, I deeply regret.

Sidebar with no page navigation

Where is my page navigation??!! Look, its not that page-navigation in sidebar is bad, ok?! it is bad if there is page-navigation alone! I never said I don't want it together with rest of the site articles!! come on, give it back to me! now!

3.Desperate sidebar item object
No way this little setback is gonna stop me.

sidebar: {
      "/1-Guide/": [
        {
          text: "Guide",
          children: ["/1-Guide/README.md", "/1-Guide/Getting Started.md"],
        },
      ],
      "/2-Account/": [
        {
          text: "Account",
          children: ["/2-Account/01 Sign Up.md", "/2-Account/02 Sign In.md"],
        },
      ],
},
Enter fullscreen mode Exit fullscreen mode

From this code alone, you could expect what will happen: when you are in /guide/ path, all the pages only show the guide articles in the sidebar whereas you will need to go to /account/ path to see account articles in the sidebar

sidebar with one path

So what, I got my page navigation back, I still feel incomplete inside!!!

4. Death Trap if you try to be smart
Silly me, why not I put all the items in the path so that even though I'm in that path, I can still navigate the whole site from the sidebar items.

sidebar: {
      "/1-Guide/": [
        {
          text: "Guide",
          children: ["/1-Guide/README.md", "/1-Guide/Getting Started.md"],
        },
        {
          text: "Account",
          children: ["/2-Account/01 Sign Up.md", "/2-Account/02 Sign In.md"],
        },
      ],

},

Enter fullscreen mode Exit fullscreen mode

Yeap, it shows all the articles in sidebar now, but when you clicked the "Sign up", it goes to /1-guide/signup.html instead of /2-account/signup.html, resulting a 404

F awesome! Stupid sidebar! I will never forgive you!!

ok, jokes aside, then I figured out in vuepress's logics, when your articles are organised into different folders, the vuepress's method is to use the navbar on top to navigate between different topics(folders), and in each folder(topic/path), the sidebar on the left shows only the articles related to that topic. That's how to navigate the whole site.


I quickly submit to Vitepress sidebar. It just renders sidebar more gracefully.

Config.js

sidebar: [
            {
              text: 'Guide',
              collapsible: true,
              items: [
                { text: 'Introduction', link: '/guide/' },
                { text: 'Getting Started', link: '/guide/gettingstarted' },
                { text: 'Get Account', link: '/guide/getaccount'},
                { text: 'Order SIMs', link: '/guide/order'},
                { text: 'Dashboard', link: '/guide/dashboard'},
                { text: 'SIM Status', link: '/guide/simstatus'},    
                { text: 'Check Your SIMs', link: '/guide/sim'},
                { text: 'CDR', link: '/guide/cdr'},

              ]
            },
            {
              text: 'SIM In Depth',
              collapsible: true,
              items: [
                { text: 'Introduction', link: '/sim/' },
                { text: 'SIM', link: '/sim/sim' }

              ]
            }
        ],

Enter fullscreen mode Exit fullscreen mode

Folder structure:
folder

Final product

vitepress sidebar

Left is the sidebar to navigate the whole site. Right side is the page navigation that shows the headers of desired depths. Top navbar is neat and clean.

No customisation, no hustle and bustle, breaks no sweat, I applaud for vitepress


Ending

In the end, of cos you could generate sidebar using javascript again, But I don't think it is ideal because from writing point of view, making a correct order is not ideal by sorting file names alphabetically, nor by sorting sequentially with time of creation. Hand written is better in this case.

End of end, I deployed it using Github action, in GitHub page and the process is rather easy. But one thing with vite, is that the error message doesn't seem to point out the error location should the css rendering fail. Pay extra attention to the contents in .md, in case there is any html/md kind of mistake, the build (yarn docs:build) will generate error like:
build error

TypeError: Invalid value used as weak map key
    at WeakMap.set (<anonymous>) 
Enter fullscreen mode Exit fullscreen mode

References:

  1. Vitepress discussion: next step for vitepress

  2. vuepress v2

  3. vitepress

Top comments (0)

🌚 Life is too short to browse without dark mode