umijs / dumi Goto Github PK
View Code? Open in Web Editor NEW📖 Static Site Generator for component library development
Home Page: https://d.umijs.org
License: MIT License
📖 Static Site Generator for component library development
Home Page: https://d.umijs.org
License: MIT License
修改yaml 需要重启服务才会生效
比如,修改
https://github.com/umijs/father-doc/blob/ba98c860d98fad71dfa5540fc9fd263d98948373/docs/demo/modal.jsx#L2
而不是lerna bootstrap
在md中写tsx没有了TS静态类型检查,也没有了TS的代码提示功能,这个有办法改进么
Can't find variable: IntersectionObserve
Find a new way to implement anchor following feature
在umijs中配置alias,tsx文件中使用import xx from '@',在father-doc dev中无作用,用umi dev运行有作用
The father doc‘s escape work is WTF.
: (
按照https://umijs.github.io/father-doc/#/config/frontmatter里面关于group.order
的说明,值越大的越排在前面,但是我配置发现不起作用。
按照上图的配置,期望的顺序应该是Web组件库、APP组件库、博文,但是实际上的顺序是APP组件库、博文、Web组件库
目前设想下来多语言的支持仍然是『约定式』的,与各位讨论下具体实现规则是否合理:
如果 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 的配置出现。
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 ?
如果仅提供在 .md 中写代码块来生成 demo 的方式,会有以下两个问题:
所以计划在 father-doc 中新增一种 markdown 扩展语法,使得编写者可以主动从外部导入 .tsx/jsx 文件生成 demo。
语法的设计非常重要,因为关乎后续编写者的内容创作,一旦方案确定,后续再难修改。设想之下,大致有如下几点要求:
加上 issue 中大家提出的方案,目前共有 5 种备选方案:
```./demo/Hello.jsx
$[](./demo/Hello.jsx)
[demo=./demo/Hello.jsx]
<!-- [demo=./demo/Hello.jsx] -->
<code src="./demo/Hello.jsx">fallback 文本</code>
需要特殊说明的是第 3 种方案,此方案可以用类似的语法扩展出更多的自定义语法,一脉相承,比如:
[badge=1.0.0-Beta.1 danger]
[alert=天干物燥 title=小心火烛 warn]
目前前 3 种方案看起来都有一些小问题:
如果大家对这 5 种方案有独特看法,或者有更好的方案,欢迎进行讨论。
使用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文件。
文档的外部壳和内嵌 demo 的样式表会进行合并且同时在一个 runtime 中被渲染,这意味着,倘若文档外部的壳中有部分全局样式,则会污染到内嵌 demo 的样式,导致开发者在预览阶段看到的效果和生产使用时未必一致,后果十分严重。
隔离无非 3 种方案:
从 Web 层面上来说它似乎就是最佳实践,但在开发 & 使用体验上它却是比较糟糕的:
这是最开始想优先考虑的方案,但在请教 @ikobe 后了解到这里的水非常深。
当一个节点成为 ShadowDOM 后,它的样式表需要手动注入到自己的节点下,这里需要经历编译 demo -> 分析 demo 所引用的全部样式表 -> 编译样式表 -> 存储样式表(也可以字符串变量存在组件中)-> 在运行时插入样式表,目前 webpack 提供的构建钩子中,虽然有能分析到依赖的钩子,但已经处于无法修改构建产物的阶段,如果要继续往这条没人走过的路上走,可能会非常黑,而且不利于后期维护。目前思考下来有如下两个方向还存有突破的可能性:
这是现在 ant.design、Docz 等采用的方案。
原理十分简单,规范外部文档壳样式的编写及应用方式,不写全局样式,对局部样式做大容器的包裹,比如对 markdown 的样式区域用 .markdown
的 className 包裹,这样 demo 区域的样式就不会受到污染。但也存在一些弊端:
分析下来,从工程角度上讲,最完美的方案肯定是 ShadowDOM;从 ROI 的角度上讲,最适合的方案肯定是主动隔离;至于 iframe,则让它去吧。
考虑到目前 father-doc 正处于 0-1 的阶段,先有可用于生产的产品乃是第一优先级的事,所以在这一阶段中,最终决定采用主动隔离的方案,后续的迭代中再去调研 ShadowDOM 的方式。
代码中,这个位置取到的 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
Related issue: #6
建议支持使用typedoc类似方式生成工具类文档
每个demo 在 router 中生成一个单独的 path。支持通过一个按钮单独一个页面打开demo。类似 stroybook,这样支持 iframe 也会很简单,我们开发组件库调试也很方便
建议子路径一律用复数。
如果不存在 index.md,就使用 readme 作为首页,下载维护 readme 和 index.md 有点累。
如何与father-build联合使用啊
只能father-build用.fatherrc.js写打包配置,
用father-doc写UI配置么,就要写两份配置,比如babel-plugin-import就要写两份
部分特殊组件 Demo 需要 position: fixed
定位能跳出 Previewer
对应 docz,doc + umi === docu
,本身也是 document 的前缀。
在文档中,组件需要访问API获取数据进行渲染,请问如何在father-doc中设置代码
写 external demo 的时候,自动补全文件扩展名吼不吼啊
<code src="./webgl/triangle.tsx" />
这里 .tsx
完全可以不写,默认查找顺序可以为 tsx
, ts
, jsx
, js
,或许也可以在配置项支持用户扩展(似乎没必要)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.