npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@mpxjs/vuese-website

v1.0.1

Published

构建示例网站

Downloads

44

Readme

介绍

本项目 fork 自 vuese,用于 mpx 项目的文档定制化生成。(感谢 vuese 的相关开发者)

快速上手

安装

npm install @mpxjs/vuese-website -g

项目配置

假设你的项目为monorepo,目录结构为:

packages
   ├── example
   |  └── pages
   ├── mpx-cube-ui // 换成你的组件库
   |  └── src
   |     └── components
   └── website
      ├── package.json
      └── website.js

其中example目录主要是为了演示组件库中组件的用法,启动后会打开一个h5,也是文档站点模拟器中显示的内容。

website文件夹为文档部署相关的内容,其中package.json内容如下:

{
  "name": "website",
  "version": "1.0.0",
  "dependencies": {
    "vue": "^3.0.0",
    "vitepress": "^1.2.3",
    "@mpxjs/vuese-website": "^1.0.0"
  }
}

website文件夹下新建website.js文件,并写入以下内容:

const path = require('path')
const website = require('@mpxjs/vuese-website').default

website({
  srcDirPath: path.resolve(__dirname, '../mpx-cube-ui/src/components'), // 组件库src目录下的components目录
  exampleDirPath: path.resolve(__dirname, '../example/pages'), // example目录下的pages目录
  outputPath: path.resolve(__dirname, './docs/components'),
  doscPath: path.resolve(__dirname, './docs'),
})

其中组件库src目录下的components目录结构如下所示:

packages/mpx-cube-ui/src/components
├── button
|  ├── index.mpx
|  ├── index.ts
└── button-group
   ├── index.mpx
   └── index.ts

exampleDirPath中的pages目录结构如下所示:

packages/example/pages
├── button
|  ├── README.md
|  ├── btn-icon.mpx
|  ├── btn-inline.mpx
|  ├── btn-light.mpx
|  ├── btn-loading.mpx
|  ├── btn-outline.mpx
|  ├── btn-primary.mpx
|  ├── btn-secondary.mpx
|  └── index.mpx
├── button-group
|  ├── README.md
|  ├── button-group-one.mpx
|  ├── button-group-two.mpx
|  ├── button-group-vertical-two.mpx
|  ├── button-group-with-context.mpx
|  └── index.mpx
├── index.mpx
└── index.ts

文档生成

文档由vitepress驱动,需要在website目录中安装对应的依赖:

npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0

然后在website目录下执行以下命令:

vuese-website

即可在项目根目录下生成基础的docs配置:

docs
├── .vitepress
|  ├── config.mjs
|  ├── sidebar
|  |  └── sidebar.js
|  └── theme
|     ├── github-light.json
|     └── index.mjs
├── components
|  ├── button-group.md
|  └── button.md
├── guide
|  └── intro.md
└── index.md

websitepackage.json中添加一条命令:

+  "serve:doc": "node website.js"

然后在目录下执行以下命令即可构建文档。

npm run serve:doc

文档启动后,默认的访问路径为:

http://localhost:5173/mpx-ui/guide/intro.html

模拟器

模拟器的默认路由为http://localhost:8090,可以通过更改docs/.vitepress/config.mjs中的iframeConfig来配置预览路径:

iframeConfig: {
  path: {
    dev: 'http://localhost:8090',
    prod: '8090'
  }
}

注意:这里的端口号要和你的example项目中的vue.config.js配置的端口号一致

devServer: {
  port: 8090
}

检查无误后启动example项目即可完成文档中模拟器的展示。

父子路由同步

父子路由同步涉及到iframe通信,为此我们提供了以下方法来进行路由同步:

declare module '@mpxjs/vuese-website/iframe-sync' {
/**
  * 监听子路由的变化
  * @param callback
  * @returns
  */
export const onPathchange: (callback?: (path: string) => void) => () => void;
/**
  * 同步路由到子窗口
  * @param to
  */
export const syncPathToChild: (to: string) => void;
}

你需要在example项目的app.ts中,监听主窗口路由的变化:

import mpx, { createApp } from '@mpxjs/core'
import { onPathchange } from '@mpxjs/vuese-website/dist/iframe-sync'

const isIframe = __mpx_mode__ === 'web' && window.parent !== window
if (isIframe) {
  onPathchange((to) => {
    mpx.redirectTo({
      // 这里需要适配你的项目路径
      url: `/pages/${to && to !== 'intro' ? `${to}/` : ''}index`
    })
  })
}

同时如果example中涉及到路由变化,也需要同步给主窗口:

const isIframe = __mpx_mode__ === 'web' && window.parent !== window
if (isIframe) {
  syncPathToChild(componentName)
}

markdown扩展语法

为了完成文档示例一体化的目标,我们制定了一些语法来提取模块儿源代码。

假设你的example目录有如下结构:

example/pages
├── button
|  ├── README.md
|  ├── btn-icon.mpx
|  ├── btn-inline.mpx
|  ├── btn-light.mpx
|  ├── btn-loading.mpx
|  ├── btn-outline.mpx
|  ├── btn-primary.mpx
|  ├── btn-secondary.mpx
|  └── index.mpx
├── button-group
|  ├── README.md
|  ├── button-group-one.mpx
|  ├── button-group-two.mpx
|  ├── button-group-vertical-two.mpx
|  ├── button-group-with-context.mpx
|  └── index.mpx
├── index.mpx
└── index.ts

基本的替换语法如下:

<!-- @example: ${README.md同级目录下的文件名称} -->

提取文件代码

用于提取目标文件的所有代码

<!-- @example: btn-primary -->

提取template代码

用于提取目标文件中的template代码

<!-- @example: btn-primary -> template -->

提取script代码

用于提取目标文件中的script代码

<!-- @example: btn-primary -> script -->

提取style代码

用于提取目标文件中的style代码

<!-- @example: btn-primary -> style -->

代码成组

用于把不同文件的代码提取到同一个代码块儿中

<!-- @group: group-name -> start -->

<!-- @example: btn-primary -> template no-wrap -->
<!-- @example: btn-secondary -> template no-wrap -->
<!-- @example: btn-light -> template -->

<!-- @group: group-name -> end -->

其中no-wrap会去掉代码块的包裹,如:

<!-- @example: btn-primary -> template no-wrap -->

渲染结果如下:

<cube-button primary>主要按钮</cube-button>

而去掉no-wrap后,则会渲染如下代码:

<template>
  <cube-button primary>主要按钮</cube-button>
</template>

这样能够更好的将多个模块儿的代码组织到一起。