V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
这是一个专门讨论 idea 的地方。

每个人的时间,资源是有限的,有的时候你或许能够想到很多 idea,但是由于现实的限制,却并不是所有的 idea 都能够成为现实。

那这个时候,不妨可以把那些 idea 分享出来,启发别人。
demomacro
V2EX  ›  奇思妙想

求一个合适的管理多份文档(Markdown)的静态站点生成器

  •  
  •   demomacro · 2021-01-15 01:01:28 +08:00 · 3239 次点击
    这是一个创建于 1393 天前的主题,其中的信息可能已经有所发展或是发生改变。

    由于饱受某些国外开发文档没有官方中文文档以及因为站点部署在海外而有时无法正常浏览的的困扰,于是决定根据官方文档自行翻译,并且在国内搭建相关站点。目前翻译文档正在进展中,但需要一个合适的静态站点生成器以建立站点。

    之前尝试过 Gitbook, Docsify, VuePress,效果都不是很理想

    Gitbook 的设计风格我其实很满意,但是 Gitbook 似乎无法按照次级目录正常处理多份文档 Docsify 其实基本满足我的要求,但是它对于相对路径的处理不理想 VuePress 不能独立配置单独某份文档

    我希望的静态站点生成器是具有类似于 Gitbook 和 Docsify 的目录结构,同时能根据目录结构设置多站点的静态站点生成器,以便优化浏览,并且使翻译文档能单独上传到 Git 存储库保存

    求助各位万能的网友提供一个好的想法

    第 1 条附言  ·  2021-01-15 19:55:37 +08:00
    看到了大家的回复,其中 mkdoc 还不错,但是 mkdocs 在目录结构上不太适合 monorepo 或者 multirepo 的多存储库协作,构建工具还是希望能够应用到 Git 存储库上,以纯代码实现自动化流程,方便后续社区维护工作。

    因为文档比较多,每份文档数十页,多份文档上百页,不能维护在同一个目录下,所以需要在独立的存储库里存放各自的目录,并最后通过自动化的方式进行统一部署……这就很令人困扰,需要的是一种文档中心的解决方案。

    Gitbook 和 docsify 的目录结构其实是很合适的,但是 Gitbook 如今已经不再维护,对于多站点的实现也不太合理; docsify 的相对路径和搜索功能又有问题。能解决以上两个问题或许也是一种解决方案。

    大家可以推荐一些适用于多站点部署的插件

    感谢大家的回复,如果还有更多好的建议希望多多提出!
    14 条回复    2021-01-16 22:01:52 +08:00
    lostberryzz
        1
    lostberryzz  
       2021-01-15 01:21:15 +08:00
    mkdocs
    steamEra
        2
    steamEra  
       2021-01-15 02:02:30 +08:00   ❤️ 1
    我的个人网站在用 Publii,看到你的问题感觉正合适。

    我没打广告,只是因为我很喜欢这个产品,

    https://marketplace.getpublii.com/product/prodocs/

    https://marketplace.getpublii.com/product/documentation/

    这俩主题很适合你,而且 Publii 官方支持 Github 和 Gitlab 还有 Netlify 之类的,更合适。建议看看。
    bearcat001
        3
    bearcat001  
       2021-01-15 03:12:18 +08:00
    MWeb 生成站点 + Github 私有库 + S3 + CloudFont
    ETiV
        4
    ETiV  
       2021-01-15 04:42:19 +08:00
    http://docs.raneto.com/

    这个的样式非常平淡,但可以自己改一改

    我拿它魔改了一个我们自己内部用的,支持多 Markdown repo + WebHook 自动更新、支持中文搜索和目录排序的文档站
    xyjtou
        5
    xyjtou  
       2021-01-15 04:46:46 +08:00 via Android
    微文档 https://weishu.vip/p/27182824

    界面类似 Docsify,
    xyjtou
        6
    xyjtou  
       2021-01-15 04:48:17 +08:00 via Android
    比 Docsify 更轻量,单文件形式
    renmu123
        7
    renmu123  
       2021-01-15 08:54:13 +08:00 via Android
    直接向官方提 pr 要求 i18n 支持,如果嫌访问慢可以做个反向代理
    missdeer
        8
    missdeer  
       2021-01-15 09:31:23 +08:00
    这需求不是应该找个合适的 jekyll,gohugo 的 theme 就行吗
    fenglangjuxu
        9
    fenglangjuxu  
       2021-01-15 10:17:15 +08:00
    hexo hugo 就可以吧
    metrue
        10
    metrue  
       2021-01-15 10:20:15 +08:00
    我给自己写了一个小 app ( https://giki.app), 不知道适不适合,对我自己而言基本满足需求, 写写 Markdown 文字,自动发布到网站,备份到云服务,感觉还行.
    lostexile
        11
    lostexile  
       2021-01-15 10:43:38 +08:00
    mweb 推荐一下
    Minamion
        12
    Minamion  
       2021-01-15 13:15:12 +08:00
    mkdocs
    muyunyun
        13
    muyunyun  
       2021-01-16 22:01:02 +08:00
    案例下我开发的 create-react-doc 。( https://github.com/MuYunyun/create-react-doc)。它支持自定义展示目录, 天然适合搭建 monorepo 类型的文档等站点。应该满足博主提到的文档相对路径显示的痛点, 如果有不满足的点可以提需求给我 ღ( ´・ᴗ・` )比心
    muyunyun
        14
    muyunyun  
       2021-01-16 22:01:52 +08:00
    @muyunyun 发现连接跳转有问题再发下链接, https://github.com/MuYunyun/create-react-doc
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   5736 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 06:09 · PVG 14:09 · LAX 22:09 · JFK 01:09
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.