Giter Site home page Giter Site logo

umijs / dumi Goto Github PK

View Code? Open in Web Editor NEW
3.4K 28.0 1.2K 5.08 MB

📖 Static Site Generator for component library development

Home Page: https://d.umijs.org

License: MIT License

JavaScript 2.80% TypeScript 69.93% Shell 0.16% Less 24.21% SCSS 0.02% Smarty 1.55% Rust 1.33%
library-development docs-generator static-site-generator umi

dumi's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

dumi's Issues

🐛[BUG]npm i father-doc@next -D 报错

🐛 bug 描述

npm i father-doc@next -D 报错。

把@next去掉就好了。

TIM截图20200111204925

📷 复现步骤

🏞 期望结果

💻 复现代码

© 版本信息

  • father-doc 版本: [e.g. 1.0.0]
  • node 版本
  • 浏览器环境
  • 开发环境 [e.g. mac OS]

🚑 其他信息

👑 [需求] 移动端组件开发

🥰 需求描述

image
移动端组件开发,预览里面的样式需要和真实环境中一致。
比如在umi 中使用的时候,开启了hd,会自动的px2rem。

如果通过配置透传开启 umi 的hd 方案,那会影响文档页面的展示。
image

🧐 解决方案

没有,还在想

🚑 其他信息

建议增加prettierrc

我发现我们本地的 prettier 规则不同,我保存的时候,会格式化一些代码,在我提交代码的时候,我还需要很小心的不要提交这些无用变更
我尝试这添加配置,但是ts里面的 ?. 不知道该怎么配置
image

🐛[BUG]group.order 不起作用

🐛 bug 描述

按照https://umijs.github.io/father-doc/#/config/frontmatter里面关于group.order的说明,值越大的越排在前面,但是我配置发现不起作用。

📷 复现步骤

image
image

🏞 期望结果

按照上图的配置,期望的顺序应该是Web组件库、APP组件库、博文,但是实际上的顺序是APP组件库、博文、Web组件库

💻 复现代码

© 版本信息

  • father-doc 版本: 1.0.0-alpha.7
  • node 版本: v10.16.0
  • 浏览器环境: 79.0.3945.79
  • 开发环境: macOS Mojave 10.14.6

🚑 其他信息

Multi-language mode design RFC

目前设想下来多语言的支持仍然是『约定式』的,与各位讨论下具体实现规则是否合理:

多语言文件检测

如果 markdown 文件的文件名组成是 filename.lang.md,则该文件会被检测为 filename.mdlang 下的渲染组件,这个 lang 原则上不限制格式,也就是说我们写 en 或者 en-US 都会被检测到。

多语言的路由生成

一旦触发上述检测条件,lang 会作为路由的前缀被生成一个新路由。例如 index.md 的路由如果是 /hello,那么 index.en.md 的路由就会是 /en/hello

多语言的切换

设想是默认主题新增一个切换语言的地方,形式应该是 Select Menu,但具体样式还没想好。

多语言的默认语言约定

只要没有带 lang 部分的 markdown,就会被当做默认语言渲染。例如,如果我的文档站默认英文,那么我的 markdown 文件应该是 index.mdindex.zh-CN.md;如果我的文档站默认中文,那么我的 markdown 文件应该是 index.mdindex.en-US.md

以上规则的设计原则只有一个,把功能尽可能约定化,也就是说理想情况下初期不会有任何关于 locales 的配置出现。

webpack alias doesn't supported in embedded demo

In local development, my project used a webpack alias,

but it doesn't work while importing module like this:

import Input from '@/components/Input';

export default () => <Input label="Basic Input" />;

Is there a better way ?

Import syntax design for external demo

背景

如果仅提供在 .md 中写代码块来生成 demo 的方式,会有以下两个问题:

  1. 复杂组件的 demo 也会比较多,.md 会混乱难以管理
  2. 在 .md 中写 tsx/jsx 无法得到编辑器的各种辅助(lint、snippets、autocomplete & etc.),在编写复杂 demo 的时候效率会非常低

所以计划在 father-doc 中新增一种 markdown 扩展语法,使得编写者可以主动从外部导入 .tsx/jsx 文件生成 demo。

要求

语法的设计非常重要,因为关乎后续编写者的内容创作,一旦方案确定,后续再难修改。设想之下,大致有如下几点要求:

  1. 维持 markdown style,不能有违和感
  2. 支持传递文件路径
  3. (欢迎补充)

提案

加上 issue 中大家提出的方案,目前共有 5 种备选方案:

  1. 去骨去尾代码块方案: ```./demo/Hello.jsx
  2. 超链接/图片师出同门方案: $[](./demo/Hello.jsx)
  3. UBB 借鉴一刀流方案:[demo=./demo/Hello.jsx]
  4. HTML 注释方案:<!-- [demo=./demo/Hello.jsx] -->
  5. code 标签降级兼容方案:<code src="./demo/Hello.jsx">fallback 文本</code>

需要特殊说明的是第 3 种方案,此方案可以用类似的语法扩展出更多的自定义语法,一脉相承,比如:

  1. 自定义标签语法,渲染类似 antd 的标签组件: [badge=1.0.0-Beta.1 danger]
  2. 自定义警告块语法,渲染类似 antd 的 Alert 组件: [alert=天干物燥 title=小心火烛 warn]

讨论

目前前 3 种方案看起来都有一些小问题:

  1. 如果次行正好为另一个代码块,无论是 transformer 的 token 识别还是编写者肉眼识别,都会造成干扰
  2. 中间的方括号没有没有实际作用
  3. 历史感很浓重,毕竟是论坛时代的标签语法

如果大家对这 5 种方案有独特看法,或者有更好的方案,欢迎进行讨论。

🐛[BUG] father-doc生成的文件部署到github page会报umi.css和umi.js 404

🐛 bug 描述

使用father-doc build命令会在项目根目录生成一个dist文件夹,包含三个文件:
index.html, umi.cssumi.js
其中,index.html里面的内容是:

<!DOCTYPE html><html><head><link rel="stylesheet" href="/umi.css"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,minimum-scale=1,user-scalable=no"><title>雷数前端</title><script>window.routerBase = "/";</script></head><body><div id="root"></div><script src="/umi.js"></script></body></html>

可以看到,引用css和js的路径是/而不是./,这样会导致在把代码推到github pages之后,无法正常加载css和js文件。

📷 复现步骤

🏞 期望结果

💻 复现代码

© 版本信息

  • father-doc 版本: 1.0.0-alpha.7
  • node 版本: v10.16.0
  • 浏览器环境: 79.0.3945.79
  • 开发环境: macOS Mojave 10.14.6

🚑 其他信息

image
image
image

Style isolation for demo previewer

背景

文档的外部壳和内嵌 demo 的样式表会进行合并且同时在一个 runtime 中被渲染,这意味着,倘若文档外部的壳中有部分全局样式,则会污染到内嵌 demo 的样式,导致开发者在预览阶段看到的效果和生产使用时未必一致,后果十分严重。

备选方案

隔离无非 3 种方案:

iframe 天然隔离

从 Web 层面上来说它似乎就是最佳实践,但在开发 & 使用体验上它却是比较糟糕的:

  1. 我们从浏览器控制台中无法直接看到 iframe 抛出的错误
  2. 倘若我们演示的是 Modal 类型的 demo,这个 demo 在 iframe 中想必会『难以自拔』

ShadowDOM 特性隔离

这是最开始想优先考虑的方案,但在请教 @ikobe 后了解到这里的水非常深。

当一个节点成为 ShadowDOM 后,它的样式表需要手动注入到自己的节点下,这里需要经历编译 demo -> 分析 demo 所引用的全部样式表 -> 编译样式表 -> 存储样式表(也可以字符串变量存在组件中)-> 在运行时插入样式表,目前 webpack 提供的构建钩子中,虽然有能分析到依赖的钩子,但已经处于无法修改构建产物的阶段,如果要继续往这条没人走过的路上走,可能会非常黑,而且不利于后期维护。目前思考下来有如下两个方向还存有突破的可能性:

  1. 在 style-loader 层面做捕获,修改 insertStyle 的行为,但仍然需要看 style-loader 能不能输出 demo 与样式表的依赖关系(尚未调研);
  2. 利用子进程对每一个 demo 做一次单独的构建到 VFS,拿到 css 产物后再回到主进程继续编译 Page Component,可行性应该是没问题,但 demo 一多性能是肯定需要考虑的问题。

为 demo 规避污染源,主动隔离

这是现在 ant.design、Docz 等采用的方案。

原理十分简单,规范外部文档壳样式的编写及应用方式,不写全局样式,对局部样式做大容器的包裹,比如对 markdown 的样式区域用 .markdown 的 className 包裹,这样 demo 区域的样式就不会受到污染。但也存在一些弊端:

  1. 虽然外部文档壳样式不会污染 demo,但倘若 demo 中有全局样式,仍然会污染外部的文档壳;
  2. 倘若同一个页面的两个 demo 之间有样式冲突,也会出现污染。

最终结论

分析下来,从工程角度上讲,最完美的方案肯定是 ShadowDOM;从 ROI 的角度上讲,最适合的方案肯定是主动隔离;至于 iframe,则让它去吧。

考虑到目前 father-doc 正处于 0-1 的阶段,先有可用于生产的产品乃是第一优先级的事,所以在这一阶段中,最终决定采用主动隔离的方案,后续的迭代中再去调研 ShadowDOM 的方式

代码里面两次单独取了yaml数据

代码中,这个位置取到的 config 没在任何地方使用。
https://github.com/umijs/father-doc/blob/d79a04cbc12f48096d36ef95d07f2b47db87855a/packages/umi-plugin-father-doc/src/transformer/index.ts#L30
真正 menu 里面取得是
https://github.com/umijs/father-doc/blob/d79a04cbc12f48096d36ef95d07f2b47db87855a/packages/umi-plugin-father-doc/src/routes/getFrontMatter.ts#L18

因为我想把页面的二级导航完成,不想再跑一次编译,所以,在这个 load 的中间过程,保留了heading 的数据,取完才发现,并没有把这个数据放回 route 中。
https://github.com/umijs/father-doc/blob/d79a04cbc12f48096d36ef95d07f2b47db87855a/packages/umi-plugin-father-doc/src/transformer/index.ts#L30
我想做的是二级导航 可以切分支 sub-layout-data
image

ts文件预览有错误

使用 code 标签引入

<code src="./demo.tsx" />

代码中是

const dataList: Item[] = new Array(10).fill(0).map((i, index) => ({ text: `第${index}个`, id: `${index}` }));

预览中是

const dataList: Item[] = [10].map(i => ({ text: `第${i}个`, id: `${i}` }));

这两者逻辑并不一致。
image

feat: 支持打开一个demo

每个demo 在 router 中生成一个单独的 path。支持通过一个按钮单独一个页面打开demo。类似 stroybook,这样支持 iframe 也会很简单,我们开发组件库调试也很方便

关于 <br> 、<img> 等标签,如何处理比较好

比如

<p>
这是一张图片<br><img src="https://avatars3.githubusercontent.com/u/11746742?s=40&v=4"></p>

效果如下:

这是一张图片

<br><img> 都是没有关闭的,比如我旧的文档想切换到 `father-doc` 会涉及到较多的修改。

不知道,你们想怎么处理这个问题,是强制用户修改为 <br /><img />,还是兼容不报错?
image

改名为 dumi

对应 docz,doc + umi === docu,本身也是 document 的前缀。

autocomplete ext at external demo src attr

写 external demo 的时候,自动补全文件扩展名吼不吼啊

<code src="./webgl/triangle.tsx" />

这里 .tsx 完全可以不写,默认查找顺序可以为 tsx, ts, jsx, js,或许也可以在配置项支持用户扩展(似乎没必要)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.