vuejs / theme

VitePress theme for vuejs.org.

Vue Theme

This is the VitePress theme for the official Vue documentation at vuejs.org.

Please note this theme is solely dedicated for vuejs.org and isn't meant to be used as a content-neutral theme. It does not follow semver and may contain hard-coded logic specific to the Vue documentation.

Development Setup

This repo can be developed on its own since it is a self-contained VitePress theme. Make sure to use pnpm as the package manager when installing deps. A demo app is available in /demo and can be run with pnpm dev:

pnpm install
pnpm dev

Developing with Real Content

To work on this theme in the context of the vuejs.org website requires cloning both repos and linking the theme into the docs repo:

1. Clone repositories:

   git clone [email protected]:vuejs/docs.git
   git clone [email protected]:vuejs/theme.git

2. Link theme into docs repo:

   # In ./theme
   pnpm install
   # Make @vue/theme available for global linking
   pnpm link --global
   
   # in ./docs
   pnpm install
   # Link theme
   pnpm link --global @vue/theme

3. Start VitePress server:

   # in ./docs
   pnpm dev

Available Scripts

Here is the list of available scripts that can be used during the development.

# Boot local dev server.
$ pnpm dev

# Build demo, then serve locally. This is for testing
# production build in the local environment.
$ pnpm serve

# Run lint via Prettier.
$ pnpm lint

# Run type check via tsc.
$ pnpm type

License

MIT

Copyright (c) 2021-present Evan You

theme's Issues

Some i18n details in this theme

During the Chinese doc site preparation, we found there were some text and labels that need to be translated but hard-written in this theme. We temporarily modified them with patch-package patch like this:

https://github.com/vuejs-translations/docs-zh-cn/blob/f8b66e7dd3862f3e3b7fb1415c886fd71056b1ad/patches/@vue+theme+1.0.2.patch

But it would be great if we can provide a way to customize them by a config file or something else.

To be noticed this patch is not the all of them, since some aria-labels and a11y elements are still under translating.

Thanks.

Dark mode shows "flash" on the page load

In production dark mode (can test via yarn docs-serve) it shows flash on the initial page load. This is because base BG color is white, and we set .dark class when app is loaded.

Is there a way to fix this issue...?

---

UPDATE from @antfu. Maybe this might work.
https://github.com/antfu/vitesse/blob/92deaa64ba7dbc8b5ebe29649b82bbe7c176c84a/index.html#L14-L21

Code block style problem

In the demo module, it is found that when the automatic line number configured for vitepress is true, the following problems will occur when using the custom code block vue-html, class line-numbers-mode is missing. There is also a problem with the font color of bright mode line size text.

Decide base icon sets to use

Currently, I'm using Feather for the icons. While I love this icon, there're few cons.

• It's "stroke" based, so I'm actually expanding the path in Adobe Illustrator and converting it to the "fille" base. Since "fill" based icons are much easier to handle.

• It would be cool if Vue Theme can re-export existing icon sets from the package, so that we have default icon sets as a design system. What is the best way to do this?

  import { VTIconActivity, VTIconArrowLeft } from 'vue-theme'

Add algolia search integration

If the search is not set, an error will appear

If algolia is not set，the following error message will appear

Implement bundle system (how to publish the package)

So, how should we publish the package? Here is the spec idea.

Vue Theme will expose many components that can be used by external packages. And they can import them like this.

import { VTButton } from 'vue-theme'

Q1. Is this what we really want? Is there any other way to consume Vue Theme components?
Q2. If yes, how can we bundle the package? Rollup I guess, but I'm not familiar with publishing Vue components, so if there's any advice, that would be awesome 🙌

Add `.html` extension to nav links

Currently, it's just using the value from the nav config. We should:

1. Add .html if missing.
2. Replace .md to .html if it's there.

Add carbon ads feature

Layout slots

Similar to the current VitePress default theme, the root layout should support injecting content at different locations via slots.

For now we just need the following:

• banner
• sidebar top
• sidebar bottom
• aside bottom (below outline)

Dark/Light mode choice is not being preserved

1. Go to vuejs.org
2. Toggle dark mode
3. Reload site, it fall backs to prefers-color-scheme thing.

It appears the script from VitePress is conflicting with the one injected here.

Outline for mobile

Code Group Component

I need a VTCodeGroup for the docs -- I rolled my own, but it's coupled to what I'm putting inside of it. We should have one that matches the theme and is generic.

vuejs/docs#1493 (comment)

Simple home page

Similar to the current VitePress Home component but with new styling.

This can be used by projects like vue-router etc.

Prev/Next links

Replace `npm` to `pnpm` on README.md

The README.md has the following sentence Make sure to use [pnpm](https://pnpm.io/) as the package manager when installing deps., but the scripts in the same file are using npm instead from pnpm. I know it works, but it can be a little confusing.

Screenshot:

Vue Docs REPL implementation via SFC Playground

The plan is to enable REPL on the docs via SFC Playground instead of codepen (initial idea from Evan).

Now, how can we embed SFC Playground...? 👀

Vue Docs home page

This should be implemented at docs repo. Listing todos here due to docs repo is public.

mockup https://www.figma.com/proto/YCtYp5hNKswmTYmFEXUYnn/Vue-Theme?page-id=0%3A1&node-id=502%3A154&viewport=-6035%2C68%2C1&scaling=min-zoom

• Hero section: Pretty much ready to be implemented. Lead text needs to be adjusted.
• Features section: Need design review. Illustrations might require longer consideration time. In that case, we could start off by this design I think.
• Sponsors section: Ready to implement. Note that Dark mode design might need extra attention (we can't make BG black because black part of logo will disappear).
• Subscription section: Ready to implement.
• Footer: Ready to implement.

Vue Docs themes page

Current page: https://vuejs.org/resources/themes.html
Mockup: https://www.figma.com/proto/YCtYp5hNKswmTYmFEXUYnn/Vue-Theme?page-id=592%3A590&node-id=861%3A1015&viewport=241%2C48%2C0.26&scaling=min-zoom

• Design mockup.

Implement navbar for VitePress

Design: https://www.figma.com/file/YCtYp5hNKswmTYmFEXUYnn/Vue-Theme?node-id=0%3A1

Missing CSS styles

• lists
• tip / warning boxes
• tables
• inline code spans

Navigation bar typo

In the navigation bar, there is a typo. It should be "Installation" instead of "Installtion"

Add active link state for nav items

Sub menu is partially hidden on small height screen

On my desktop, hovering the Ecosystem menu link show the very long sub menu and the end is cropped by the screen bottom.

See:
https://user-images.githubusercontent.com/2922851/228395667-2ac6ac33-cdb5-47b2-bee4-7b95a9d0fc29.mp4

I see two solutions to that:

• Remove items or optimize space between categories
• Add a max-height with an overflow auto to always show every items and let scroll in big submenu

hLn9aardzL.mp4

能将 vuejs.org 官网的ui封装成一个Vue的UI框架吗？

真的喜欢 https://vuejs.org 官网的UI样式，
比传统的 Vue UI框架好看，
能将它封装成一个像 element-ui (https://element-plus.org/) 一样的 Vue UI框架吗？
目前流行的 Vue UI 框架的样式设计像是停留在十年前，真的太丑太LOW了，根本不符合现在年轻人的审美。

Add active link state for sidebar links

Collapsable sidebar groups

Will @vue/theme be the theme for vitepress?

Hello~

The new vue3 documentation will be the best development documentation.
Thanks to the vue team for bringing us such a good documentation experience.

Also want to know, @vue/theme will optimize the hardcoded logic specific to Vue documentation to become the official vitepress theme?

Thanks!

Shuffle team members

Currently, the team page members order is not shuffled due to having trouble simple shuffling not working on production build. Investigate it, and let's implement the shuffle feature!

href on div element

theme/src/vitepress/components/VPNavBarLocaleItems.vue

Lines 22 to 26 in c48d95c

	<div
	:href="item.link"
	class="vt-locales-menu-item-text"
	@click="onLocaleSelect(item)"
	>

The div element has an href attribute here, but according to the HTML Standard, only global attributes are allowed. It would be great if it can be changed to something like data-href.

NavBar problem

Problem Description:

When the navigation bar is configured in Chinese, there will be a little style problem.For example, the vue3 in Chinese documents.When your browser window is between 768px~800px, the following will happen

Solution

I found https://github.com/vuejs/theme/blob/main/src/vitepress/components/VPNavBar.vue#L37 and add :
white-space: nowrap;
this problem is solved

layout slots Not enough

(https://github.com/vuejs/theme/tree/main/src/vitepress/components)/VPNavBarTitle.vue

In this file, there are many places that are hard-coded, such as logo images and vue.js, can we leave the slot and let us define it ourselves

thank you!

Incorrect aside sticky position

When there is a top banner and no sidebar, the sticky position of the aside is incorrect.

You can find this bug on vue doc.

Related: vitepress issue.

Vue Docs partners page

Current page: https://vuejs.org/resources/partners.html

mockup https://www.figma.com/proto/YCtYp5hNKswmTYmFEXUYnn/Vue-Theme?page-id=592%3A590&node-id=597%3A4659&viewport=-1181%2C148%2C0.47783252596855164&scaling=min-zoom

• Design mockup -> Review in progress.

Use shiki's latest API for code block with line highlights

Was poking around the new site to see Shiki's usage in the wild. I think the current line highlighting solution can be simplified.

Shiki 0.10.0 adds an API to highlight specific lines. For example, this:

highlighter
  .codeToHtml(code, {
    lang,
    theme,
    lineOptions: [
      { line: 2, classes: ['highlighted']}
    ]
  })

generates something like:

<span class="line"></span>
<span class="line highlighted"></span>
<span class="line"></span>

The current line highlighter uses a workaround by rendering two layers, one with the highlighted code and the other one with all <br>. By using the API it cuts some HTML for code blocks with highlighted lines:

I have a PR - should I wait until this repo is more stabalized to send it?

Add sponsors section to doc page

Use Chinese Title Questions

Fix anchor link not working

This is because we're not setting correct class name to the doc container. VitePress router is referencing the element by the class or id (I forgot).

Add outlines section to the doc page

Duplicated language specifier in code blocks

Refer Vue.js docs:

Caused by vuejs/vitepress#875 -- need to update styles here, and maybe add copy code button :)

Probably line highlighting will be broken too.

Search shortcut for Windows is broken

Need to fix this one. The CTRL icon(?) is not looking fantastic.

Type issue on `ariaAnnouncer`

On https://github.com/vuejs/theme/blob/main/src/vitepress/config.ts#L132, it seems that the type is wrong according to https://github.com/vuejs/theme/blob/main/demo/.vitepress/config.js#L379.

Auto sidebar

Missing `active` class on active sidebar item for examples page

no active styles after load/reload page
https://vuejs.org/examples/#handling-input

Vue Docs team page

This should be implemented at docs repo.

mockup https://www.figma.com/proto/YCtYp5hNKswmTYmFEXUYnn/Vue-Theme?page-id=592%3A590&node-id=592%3A2845&viewport=-1181%2C148%2C0.47783252596855164&scaling=min-zoom

• Design in mockups.
• Ready to implement.