Giter Site home page Giter Site logo

jaywcjlove / idoc Goto Github PK

View Code? Open in Web Editor NEW
272.0 13.0 64.0 3.73 MB

:book: Simple document generation tool! Dependence Node.js run.

Home Page: https://git.io/idoc

License: MIT License

JavaScript 32.89% CSS 10.16% TypeScript 48.71% EJS 8.24%
document generator idoc nodejs book

idoc's Introduction

idoc

NPM version CI Dependents Repo npm Downloads npm Downloads npm Downloads

Generate static pages from all Markdown in a folder.

  ,,        ,,
  db      `7MM
            MM
`7MM   ,M""bMM  ,pW"Wq.   ,p6"bo
  MM ,AP    MM 6W'   `Wb 6M'  OO
  MM 8MI    MM 8M     M8 8M
  MM `Mb    MM YA.   ,A9 YM.    ,
.JMML.`Wbmd"MML.`Ybmd9'   YMbmd'

Quick Start

Create a idoc site using the beautiful defalut theme.

$ npx idoc init myapp

Or

$ sudo npm i idoc -g
$ idoc init myapp

Running the idoc init myapp generator from the command line will create a directory structure with the following elements:

├── docs
│   ├── README.md
│   └── about.md
├── package.json
└── idoc.yml

Or use in github actions

- name: Create idoc config.
  run: |
    cat > idoc.yml << EOF
    site: "Rehype Rewrite {{version}}"
    menus:
      Home: index.html
    EOF

- run: npm install [email protected] -g
- run: idoc --output="www"

Command Help

Usage: idoc [init|new][options] [--help|h] [--version|v]

Options:

  -v, --version, Show version number
  -h, --help,    Displays help information.
  -f, --force,   Force file regeneration.
  -s, --site,    Set website name.
  -d, --dir <dir-path>, Markdown file directory. defalut(docs)
  -o, --output <dir-path>, Output directory. defalut(dist)
  -w, --watch,   Watch and compile Markdown files.
  -t, --theme,   Customize theme settings. defalut(defalut)
  -m, --minify,  minify HTML

Example:

  $ idoc init <folder>
  $ idoc new introduce/README.md
  $ idoc new introduce/README.md "Hello World" -f
  $ idoc --theme="defalut"
  $ idoc --dir="docs"
  $ idoc --output="dist"
  $ idoc --watch --output="www"

Compiled with idoc

My macOS app's official website is also built with it:

Copybook Generator DevTutor for SwiftUI RegexMate Time Passage Iconize Folder Textsound Saver Create Custom Symbols DevHub Resume Revise Palette Genius Symbol Scribe

Repo Starred Last Commit Website
Awesome Mac Github Stars GitHub last commit Preview Website
Awesome UIKit Github Stars GitHub last commit Preview Website
MySQL Tutorial Github Stars GitHub last commit Preview Website
Docker Tutorial Github Stars GitHub last commit Preview Website
Nginx Tutorial Github Stars GitHub last commit Preview Website
Vim Web Github Stars GitHub last commit Preview Website
Git Tips Github Stars GitHub last commit Preview Website
Shell Tutorial Github Stars GitHub last commit Preview Website
SwiftUI Example Github Stars GitHub last commit Preview Website
Swift Tutorial Github Stars GitHub last commit Preview Website
Handbook Github Stars GitHub last commit Preview Website
GitHub Actions Github Stars GitHub last commit Preview Website
HTML Tutorial Github Stars GitHub last commit Preview Website
C Tutorial Github Stars GitHub last commit Preview Website
React Native Github Stars GitHub last commit Preview Website
TypeNexus Github Stars GitHub last commit Preview Website
Awesome ChatGPT Github Stars GitHub last commit Preview Website
React Components Awesome Github Stars GitHub last commit Preview Website
Repo Starred Downloads Website
rehype-rewrite Github Stars NPM Downloads Preview Website
rehype-attr Github Stars NPM Downloads Preview Website
rehype-ignore Github Stars NPM Downloads Preview Website
rehype-video Github Stars NPM Downloads Preview Website
remark-github-blockquote-alert Github Stars NPM Downloads Preview Website
store.js Github Stars NPM Downloads Preview Website
cookie.js Github Stars NPM Downloads Preview Website
auto-config-loader Github Stars NPM Downloads Preview Website
chmod-cli Github Stars NPM Downloads Preview Website
local-ip-url Github Stars NPM Downloads Preview Website
path-templater Github Stars NPM Downloads Preview Website
html-to-markdown-cli Github Stars NPM Downloads Preview Website
colors-named Github Stars NPM Downloads Preview Website
colors-named-hex Github Stars NPM Downloads Preview Website
colors-named-decimal Github Stars NPM Downloads Preview Website
chinese-numerals Github Stars NPM Downloads Preview Website
image2uri Github Stars NPM Downloads Preview Website
svgtofont Github Stars NPM Downloads Preview Website
console-emojis Github Stars NPM Downloads Preview Website
compile-less Github Stars NPM Downloads Preview Website

Contributors

As always, thanks to our amazing contributors!

Made with action-contributors.

License

Licensed under the MIT License.

idoc's People

Contributors

jaywcjlove avatar maskleo avatar renovate[bot] avatar sinchang avatar yubaoquan avatar zhangrenyang avatar zhufengnodejs avatar

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

idoc's Issues

0.2.12版本window下bug

// 0.2.12 版本

$ idoc -v
module.js:327
    throw err;
    ^

Error: Cannot find module 'colorful'
    at Function.Module._resolveFilename (module.js:325:15)
    at Function.Module._load (module.js:276:25)
    at Module.require (module.js:353:17)

segmentfault文章右侧导航

看到@jaywcjlove 也经常逛segmentfault,有木有觉得他们的文章的右侧文章目录部分很性感,鼠标向下滑动时自动定位到右侧的某个目录,且目录一直定位于右侧可视区内。这种体验比较nice,期待idoc也有这样的实现,就碉堡了。

移动端导航不能响应式

文章内容在移动端的阅读体验很赞,但是导航部分全部错乱了,建议把logo放在导航左上角,导航右上角放一个点击按钮的icon,点击后下拉或是右侧滑动展示导航的菜单。这样在移动端就太赞了。

执行idoc命令时报错

D:\vip_data\idoc>idoc
C:\Users\Administrator\AppData\Roaming\npm\node_modules\idoc\node_modules\colorful\index.js:22
    Object.defineProperty(String.prototype, key, {
           ^

TypeError: Cannot redefine property: black
    at Function.defineProperty (native)
    at C:\Users\Administrator\AppData\Roaming\npm\node_modules\idoc\node_modules\colorful\index.js:22:12
    at Array.forEach (native)
    at Object.exports.toxic (C:\Users\Administrator\AppData\Roaming\npm\node_modules\idoc\node_modules\colorful\index.js:20:23)

    at Object.<anonymous> (C:\Users\Administrator\AppData\Roaming\npm\node_modules\idoc\.bin\idoc.js:7:21)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)

重构 idoc v1 开发计划

Downloads NPM version Build

在工作的原因,idoc 停滞五六年,中间尝试使用 react 封装 rdoc 工具,同时为了小的工具方便生成单个静态页面,作为文档网站,搞了个 markdown-to-html-cli ,同时支持 GitHub Action ,在 CI 中生成页面,及时你不是一个 node 项目,也可以生成简单的文档网站。

在一系列的工具、经验积攒下,让我重构 idoc 变得非常简单,主要程序开发只花费了 1 天时间,剩下的是各种小功能的慢慢集成,可以使用 beta 版本尝鲜,使用下面命令初始化一个项目:

$ npx idoc init myapp
$ npx idoc@1 init myapp

开发任务:

idoc init 报错

/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:549
    throw e;
          ^
ReferenceError: answers is not defined
    at menu_json (/usr/local/lib/node_modules/idoc/lib/menu_json.js:26:44)
    at null.completed (/usr/local/lib/node_modules/idoc/lib/init.js:136:31)
    at PromptUI.onCompletion (/usr/local/lib/node_modules/idoc/node_modules/inquirer/lib/ui/prompt.js:56:10)
    at AnonymousObserver.Rx.AnonymousObserver.AnonymousObserver.completed (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1826:12)
    at AnonymousObserver.Rx.internals.AbstractObserver.AbstractObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1763:14)
    at AnonymousObserver.tryCatcher (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:537:29)
    at AutoDetachObserverPrototype.completed (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:5435:56)
    at AutoDetachObserver.Rx.internals.AbstractObserver.AbstractObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1763:14)
    at InnerObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:2885:65)
    at InnerObserver.tryCatcher (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:537:29)

idoc init 初始化,如果目录为空就报错

readline.js:924
            throw err;
            ^

ReferenceError: answers is not defined
    at menu_json (/usr/local/lib/node_modules/idoc/lib/menu_json.js:26:44)
    at null.completed (/usr/local/lib/node_modules/idoc/lib/init.js:136:31)
    at PromptUI.onCompletion (/usr/local/lib/node_modules/idoc/node_modules/inquirer/lib/ui/prompt.js:56:10)
    at AnonymousObserver.Rx.AnonymousObserver.AnonymousObserver.completed (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1826:12)
    at AnonymousObserver.Rx.internals.AbstractObserver.AbstractObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1763:14)
    at AnonymousObserver.tryCatcher (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:537:29)
    at AutoDetachObserverPrototype.completed (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:5435:56)
    at AutoDetachObserver.Rx.internals.AbstractObserver.AbstractObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:1763:14)
    at InnerObserver.onCompleted (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:2885:65)
    at InnerObserver.tryCatcher (/usr/local/lib/node_modules/idoc/node_modules/inquirer/node_modules/rx-lite/rx.lite.js:537:29)

解决文档编辑时间问题

文档编辑时间是根据本地文档编辑时间生成,但是到了 CI 中,文件是重新 clone 创建的,两种解决方案解决文档 编辑时间 错误问题。

  1. 将所有文档编辑时间缓存到一个文件(.idoc_cache 目录)中,提交到 GitHub 中,编译创建从缓存中读取文档编辑时间
  2. 获取 git 中文档变更时间。

更新到0.2.0后出错了

$ idoc build
Generates "README.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "关于我.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "前端工程化/前端模板.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "前端工程化/前端集成解决方案.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "工作文档/演示.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "性能优化/jshint代码质量检测.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "性能优化/性能优化待办事项.md" Success ! Mon Oct 26 2015 10:38:39 GMT+0800 (**标准时间)
Generates "性能优化/性能优化点总结.md" Success ! Mon Oct 26 2015 10:38:40 GMT+0800 (**标准时间)
Generates "技术分享/React技术分享.md" Success ! Mon Oct 26 2015 10:38:40 GMT+0800 (**标准时间)
fs.js:747
return binding.mkdir(pathModule._makeLong(path),
^
Error: ENOENT, no such file or directory 'd:\website\MyTechBook\static\css'
at Error (native)
at Object.fs.mkdirSync (fs.js:747:18)
at mkdirsSync (c:\Program Files\nodejs\node_global\node_modules\idoc\lib\copy.js:75:31)
at existDir (c:\Program Files\nodejs\node_global\node_modules\idoc\lib\copy.js:121:5)
at c:\Program Files\nodejs\node_global\node_modules\idoc\lib\copy.js:113:13
at Array.forEach (native)
at copyDir (c:\Program Files\nodejs\node_global\node_modules\idoc\lib\copy.js:106:11)
at copy (c:\Program Files\nodejs\node_global\node_modules\idoc\lib\copy.js:99:9)
at build (c:\Program Files\nodejs\node_global\node_modules\idoc\lib\build.js:96:5)
at module.exports (c:\Program Files\nodejs\node_global\node_modules\idoc\index.js:33:16)

idoc -s运行时如果修改文件报错停止运行

$ idoc -s
Waiting...
idoc is running. Press Ctrl+C to stop.

Static file server running at

=> http://localhost:1987

Initial scan complete. Ready for changes.

fs.js:747
return binding.mkdir(pathModule._makeLong(path),
^
Error: ENOENT, no such file or directory 'd:\website\MyTechBook\html\d:\website\MyTechBook\md\鎶€鏈垎浜?

idoc -s 报错

/usr/local/lib/node_modules/idoc/node_modules/ssr/index.js:181
    if(argv.proxy){
           ^

TypeError: Cannot read property 'proxy' of undefined
    at server (/usr/local/lib/node_modules/idoc/node_modules/ssr/index.js:181:12)
    at module.exports (/usr/local/lib/node_modules/idoc/index.js:40:9)
    at Object.<anonymous> (/usr/local/lib/node_modules/idoc/.bin/idoc.js:65:1)
    at Module._compile (module.js:413:34)
    at Object.Module._extensions..js (module.js:422:10)
    at Module.load (module.js:357:32)
    at Function.Module._load (module.js:314:12)
    at Function.Module.runMain (module.js:447:10)
    at startup (node.js:139:18)
    at node.js:999:3

建议提供主题的插件机制

今天闲来想自定义一个主题,看了提供的文档,看的不是特别清晰。想自定义导航的部分,发现提供出来的接口是封装好的html片段了。

所以建议提供一个用户自定义封装主题的机制,并且提供导航和文章主体等接口。这样大家都能参与进来丰富基于idoc的主题制作了。

几个UI建议

目前还没看自定义主题部分的内容,就暂时先提两个UI相关的建议吧:

  • 用idoc做了个文档站点,可以参观下:郭永峰
  • 右上角的fork按钮,是否考虑替换为fork的那行图片
  • 首页部分的色块区域,是否考虑设置为用户可自定义的一张大图,这样看着高大上,哈哈
  • 导航部分是否考虑用bootstrap的navbar,这样提的想法是自适应,当然,自适应要做的话就不光只是导航部分了

以上是部分建议,辛苦作者 @jaywcjlove 了。

HTML 示例代码运行预览

image

之前的设计

<!--DemoStart--> 
```html
<div style="color:red;">
  Test Preview HTML Example.
</div>
<script>
console.log('test')
</script>
\```
<!--End-->

优化变更之后,在标记语言之后,添加预览标记 demo:preview,生成预览效果

```html demo:preview
<div style="color:red;">
  Test Preview HTML Example.
</div>
<script>
console.log('test')
</script>
\```

git init 失败

windows 10 系统,本地node 4.4.5 的版本,不知道是什么原因

23 8 i8mvtq0 w _qq z902

改进交流

idoc很好用,同时也发现几个改进的点:

  • 当菜单栏过长的时候,换行了,样式错乱
  • 制定几种不同的风格可以选择,目前只有default
  • 如果支持二级目录或三级目录,第一个问题就很帅气的解决了

模板变量被覆盖问题

为了方便开发,默认全局模板变量,会被局部变量配置所覆盖。

需要添加 globalpage 两个变量去缓存 历史 变量。

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Other Branches

These updates are pending. To force PRs open, click the checkbox below.

  • chore(deps): update actions/checkout action to v4
  • chore(deps): update actions/setup-node action to v4

Detected dependencies

github-actions
.github/workflows/ci.yml
  • actions/checkout v3
  • actions/setup-node v3
  • actions/checkout v3
  • actions/setup-node v3
.github/workflows/main.yml
  • actions/checkout v4
  • actions/setup-node v4
  • peaceiris/actions-gh-pages v4
  • ncipollo/release-action v1
npm
package.json
  • @types/ejs ^3.1.0
  • @types/fs-extra ~11.0.0
  • @types/inquirer ^9.0.0
  • @types/micromatch ^4.0.2
  • @types/minimist ~1.2.2
  • @uiw/formatter ~2.0.0
  • @wcj/markdown-to-html ^3.0.0
  • auto-config-loader ^1.7.4
  • chokidar ^3.5.3
  • ejs ^3.1.6
  • fs-extra ~11.2.0
  • image2uri ^2.0.0
  • inquirer ^9.0.0
  • micromatch ^4.0.5
  • minimist ~1.2.6
  • recursive-readdir-files ^2.3.0
  • rehype-autolink-headings ~7.1.0
  • rehype-format ^5.0.0
  • rehype-ignore ~2.0.0
  • rehype-minify-whitespace ^6.0.0
  • rehype-parse ^9.0.0
  • rehype-slug ~6.0.0
  • remark-github-blockquote-alert ^1.1.0
  • yaml ^2.0.0
  • husky ^9.0.11
  • lint-staged ^15.0.0
  • prettier ^3.0.0
  • tsbb ^4.1.5
  • node >=16.0.0
template/package.json

  • Check this box to trigger a request for Renovate to run again on this repository

window 8.1 idoc build 报错

window 8.1 上面报错idoc v0.2.4

fs.js:799
  return binding.mkdir(pathModule._makeLong(path),
                 ^

Error: ENOENT: no such file or directory, mkdir 'E:\Wing's Github\idoc\html\E:\W
ing's Github\idoc'
    at Error (native)
    at Object.fs.mkdirSync (fs.js:799:18)
    at mkdirsSync (C:\Users\wing324\AppData\Roaming\npm\node_modules\idoc\lib\fi
le.js:53:31)
    at Object.write (C:\Users\wing324\AppData\Roaming\npm\node_modules\idoc\lib\
file.js:105:5)
    at C:\Users\wing324\AppData\Roaming\npm\node_modules\idoc\lib\build.js:91:14

    at Array.forEach (native)
    at build (C:\Users\wing324\AppData\Roaming\npm\node_modules\idoc\lib\build.j
s:48:13)
    at module.exports (C:\Users\wing324\AppData\Roaming\npm\node_modules\idoc\in
dex.js:33:16)
    at Object.<anonymous> (C:\Users\wing324\AppData\Roaming\npm\node_modules\ido
c\.bin\idoc.js:67:1)
    at Module._compile (module.js:434:26)

首页资源拷贝问题

├── docs
│   ├── README.md   # 👈 定制首页,如果不存在,默认为项目根目录
│   └── about.md
├── package.json
└── idoc.yml

项目根目录 README.md 作为首页引入图片等资源,会导致图片不存在,需要拷贝复制到输出目录

建议:能否有个替换设置

话说能否有个替换机制,比如
[常用方法](常用方法.md)

生成html的时候
<a href="常用方法.md">常用方法</a>

会导致链接(⊙_⊙)?(其实这是看云文档的)

请忽略

A

A

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.