Giter Site home page Giter Site logo

umijs / dumi Goto Github PK

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

📖 Static Site Generator for component library development

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

License: MIT License

JavaScript 2.96% TypeScript 69.82% Shell 0.16% Less 24.15% SCSS 0.02% Smarty 1.56% Rust 1.33%
docs-generator library-development static-site-generator umi

dumi's Issues

改名为 dumi

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

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 的方式。

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

🥰 需求描述

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

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

🧐 解决方案

没有，还在想

🚑 其他信息

代码里面两次单独取了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

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 种方案有独特看法，或者有更好的方案，欢迎进行讨论。

feat: 支持打开一个demo

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

🐛[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]

🚑 其他信息

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

比如

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

效果如下：

这是一张图片

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

不知道，你们想怎么处理这个问题，是强制用户修改为 <br /> 和 <img />，还是兼容不报错？
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

建议增加prettierrc

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

Multi-language mode design RFC

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

多语言文件检测

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

多语言的路由生成

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

多语言的切换

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

多语言的默认语言约定

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

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

🐛[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

🚑 其他信息

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 ?

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

🐛 bug 描述

使用father-doc build命令会在项目根目录生成一个dist文件夹，包含三个文件：
index.html, umi.css和umi.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

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.