minidocs

NPM version js-standard-style

build a minimalist site for your documentation

This module generates a documentation site from two simple components:

  1. A collection of markdown documents
  2. A hierarchical object specifying your table of contents

This module is intentionally simpler and more opinionated than something like Jekyll or Sphinx. Depending on what you're looking for, that might be good, because it's easier to reason about, or bad, because it's less flexible! It'll probably be most useful if your documentation already consists entirely of markdown files, and it composes well with any tools that generate markdown, for example ecosystem-docs, which pulls README files from a collection of GitHub repositories.

Sites can be built using a command-line tool, or using the library as a module with browserify. There are options for specifying a project logo, custom css, and other basic formatting.Support for themes coming soon! PRs welcome!

Here are some example sites built with minidocs:

install

command-line

Install as a command-line tool

npm install -g minidocs

library

Add to your project with

npm install --save minidocs

examples

using minidocs on the command-line

Just specify the location of your markdown files, the table of contents, the output location, and build the site

minidocs docs/ --contents contents.json --output site/

The folder site will now contain the html, js, and css for your site.

Have a images or other files you'd like to include? You can copy a directory into the build of your site with the --assets option:

minidocs docs/ --contents contents.json --output site/ --assets images

Want to change the styles? Use the --css option to include a custom stylesheet.

minidocs docs/ --contents contents.json --output site/ --css style.css

See all other cli options.

using minidocs as a JS module

Create a table of contents in a file named contents.json:

{
  "overview": {
    "about": "about.md"
  },
  "animals": {
    "furry": {
      "sheep": "sheep.md"
    },
    "pink": {
      "pig": "pig.md"
    }
  }
}

Then build the site and add it to the page with

var minidocs = require('minidocs')

var app = minidocs({
  contents: './contents.json',
  markdown: './markdown',,
  logo: './logo.svg'
})

var tree = app.start()
document.body.appendChild(tree)

This assumes you have the files about.md, sheep.md, and pig.md inside a local folder markdown.

To run this in the browser you'll need to use the minidocs transform with browserify or budo:

browserify example:

browserify index.js -t minidocs/transform > bundle.js

budo example:

budo index.js:bundle.js -P -- -t minidocs/transform

You can also add transforms to your project by adding a browserify field to the package.json file with a transform array:

"browserify": {
  "transform": [
    "minidocs/transform"
  ]
}

about the minidocs transform

Packaged with minidocs is a transform that takes care of reading the contents file, the markdown files, highlighting code in the markdown, and bundling the JS and CSS.

The minidocs transform is only necessary when using minidocs as a JS module, not when using the minidocs cli tool.

run the example

To run a full example, clone this repository, go into the folder example then call

npm install
npm start

usage

command-line

Usage:
  minidocs {sourceDir} -c {contents.json} -o {buildDir}

Options:
  * --contents, -c     JSON file that defines the table of contents
  * --output, -o       Directory for built site [site]
  * --title, -t        Project name [name of current directory]
  * --logo, -l         Project logo
  * --css, -s          Optional stylesheet
  * --assets, -a       Directory of assets to be copied to the built site
  * --initial, -i      Page to use for root url
  * --pushstate, -p    Create a 200.html file for hosting services like surge.sh
  * --basedir, -b      Base directory of the site
  * --full-html, -f    Create HTML files for all routes. Useful for GitHub Pages. [false]
  * --help, -h         Show this help message

library

var minidocs = require('minidocs')

var app = minidocs(opts)

Where opts is an object that can specify the following options

  • contents the path to a JSON file or JS module with the table of contents, required
  • markdown the path to the directory of markdown files
  • styles a stylesheet, if not required will only use base styles
  • logo relative file path to a logo file, if unspecified will not include a logo
  • initial which document to show on load, if unspecified will load the first document
  • root a DOM node to append to, if unspecified will append to document.body
  • basedir the base route of the minidocs app (useful if published as a project on github pages)

var tree = app.start(rootId?, opts)

The start method accepts the same options as choo's start method.

This generates the html tree of the application that can be added to the DOM like this:

var tree = app.start()
document.body.appendChild(tree)

var html = app.toString(route, state)

The toString method accepts the same options as choo's toString method

We use this in the command-line tool to generate the static files of the site.

deploying minidocs

surge.sh

surge.sh supports HTML5 pushstate if you have a 200.html file in your built site. You can either create that file yourself when using minidocs as a JS module, or you can build the site with the minidocs cli tool and the --pushstate option:

minidocs docs/ -c contents.json --pushstate -o site/
Deploy with the surge command

You can use the surge module to push the built site to the surge.sh service.

Install surge:

npm install --save-dev surge

Create a deploy npm script:

"scripts": {
  "deploy": "surge dist"
}

Publish your site:

npm run deploy

github pages

GitHub Pages doesn't support HTML5 pushstate, so you have two options:

1. Generate the site with the minidocs cli

Build a minidocs site with the cli and the --full-html option:

minidocs path/to/docs/dir -c contents.json -o site --full-html

This creates an HTML file for each route of the site, so that on initial page load all content is sent from the server, and once the JS is loaded the minidocs app takes over all routing.

2. Use hash routing with the JS module

To use hash routing, start the app with the { hash: true } option in the minidocs.start method:

var tree = app.start({ hash: true })
document.body.appendChild(tree)
Deploy with the gh-pages command

You can use the gh-pages module to push the built site to the gh-pages branch of your repo.

Note: if you're deploying a project at a basedir like username.github.io/project-name, you'll want to use the --basedir /project-name option

Install gh-pages:

npm install --save-dev gh-pages

Create a deploy npm script:

"scripts": {
  "deploy": "gh-pages -d dist"
}

Publish your site:

npm run deploy

license

MIT



minidocs

NPM版本 JS-标准式

build a minimalist site for your documentation

此模块通过两个简单的组件生成文档站点:

  1. A collection of markdown documents
  2. A hierarchical object specifying your table of contents

此模块比 Jekyll 狮身人面像。根据你所寻找的内容,这可能是好的,因为它更容易理解或不好,因为它不那么灵活!如果您的文档完全由markdown文件组成,那么它可能是最有用的,它与生成降价的任何工具组合良好,例如 生态系统文档 ,它从一组GitHub存储库中提取README文件。

可以使用命令行工具构建站点,也可以使用库作为具有browserify的模块。有指定项目标志,自定义CSS和其他基本格式的选项。支持主题即将推出!公关欢迎!

以下是使用 minidocs 构建的一些示例网站:

安装

命令行

作为命令行工具安装

npm install -g minidocs

使用

添加到您的项目
npm install –save minidocs

示例

在命令行

上使用minidocs

只需指定您的缩位文件的位置,目录,输出位置,并构建站点

minidocs docs/ –contents contents.json –output site/

文件夹 site 现在将包含您的站点的 html js css 。 p>

要包含图片或其他文件?您可以使用 - assets 选项将目录复制到您网站的构建中:

minidocs docs/ –contents contents.json –output site/ –assets images

想要更改样式?使用 - css 选项包含自定义样式表。

minidocs docs/ –contents contents.json –output site/ –css style.css

查看所有其他cli选项。

使用minidocs作为JS模块

在名为 contents.json 的文件中创建一个目录:

{
  "overview": {
    "about": "about.md"
  },
  "animals": {
    "furry": {
      "sheep": "sheep.md"
    },
    "pink": {
      "pig": "pig.md"
    }
  }
}

然后构建站点,并使用

将其添加到页面
var minidocs = require('minidocs')

var app = minidocs({ contents: './contents.json', markdown: './markdown',, logo: './logo.svg' })

var tree = app.start() document.body.appendChild(tree)

这假设您在本地文件夹中的文件 about.md sheep.md pig.md

要在浏览器中运行,您需要使用带有browserify或budo的minidocs转换:

browserify示例:

browserify index.js -t minidocs/transform > bundle.js

budo示例:

budo index.js:bundle.js -P – -t minidocs/transform
您还可以通过使用变换数组向 package.json 文件添加 browserify 字段,将变换添加到项目中:

"browserify": {
  "transform": [
    "minidocs/transform"
  ]
}

关于minidocs变换

使用minidocs打包是一种转换,它负责阅读内容文件,降价文件,降价中的突出显示代码以及捆绑JS和CSS。

在使用minidocs作为JS模块时,minidocs变换是必需的,而不是使用minidocs cli工具时。

运行示例

要运行完整示例,请克隆此存储库,进入 示例 文件夹,然后调用

npm install
npm start

用法

命令行

Usage:
  minidocs {sourceDir} -c {contents.json} -o {buildDir}

Options: * –contents, -c JSON file that defines the table of contents * –output, -o Directory for built site [site] * –title, -t Project name [name of current directory] * –logo, -l Project logo * –css, -s Optional stylesheet * –assets, -a Directory of assets to be copied to the built site * –initial, -i Page to use for root url * –pushstate, -p Create a 200.html file for hosting services like surge.sh * –basedir, -b Base directory of the site * –full-html, -f Create HTML files for all routes. Useful for GitHub Pages. [false] * –help, -h Show this help message

var minidocs = require('minidocs')

var app = minidocs(opts)

其中 opts 是一个可以指定以下选项

的对象
  • 内容具有目录的JSON文件或JS模块的路径,
  • markdown
  • style 如果不需要,样式表将只使用基本样式
  • logo 标志文件的相对文件路径,如果未指定将不包含徽标
  • initial 要显示加载的文档,如果未指定将加载第一个文档
  • 要追加的DOM节点,如果未指定将附加到 document.body
  • basedir minidocs应用程序的基本路线(如果在github页面上作为项目发布,则有用)

var tree = app.start(rootId?, opts)

开始方法接受与 choo的开始</代码>方法

这将生成可以像DOM这样添加到DOM的应用程序的html树:

var tree = app.start()
document.body.appendChild(tree)

var html = app.toString(route, state)

toString 方法接受与 choo的 toString </代码>方法

我们在命令行工具中使用它来生成站点的静态文件。

部署minidocs

surge.sh

surge.sh 支持HTML5 pushstate,如果您的建站中有一个200.html文件。您可以在使用minidocs作为JS模块时自己创建该文件,也可以使用minidocs cli工具和 - pushstate 选项构建站点:

minidocs docs/ -c contents.json –pushstate -o site/
Deploy with the surge command

您可以使用 浪涌 模块将内置网站推送到 surge.sh服务

安装浪涌

npm install –save-dev surge

创建一个 deploy npm脚本:

"scripts": {
  "deploy": "surge dist"
}

发布您的网站:

npm run deploy

github页

GitHub Pages不支持HTML5 pushstate,因此您有两个选项:

1. Generate the site with the minidocs cli

使用cli和 - full-html 选项构建一个minidocs站点:

minidocs path/to/docs/dir -c contents.json -o site –full-html

这将为网站的每个路由创建一个HTML文件,以便在初始页面加载时,所有内容都将从服务器发送,一旦加载了JS,则minidocs应用程序将接管所有路由。

2. Use hash routing with the JS module

要使用散列路由,请使用 minidocs.start 方法中的 {hash:true} 选项启动应用程序:

var tree = app.start({ hash: true })
document.body.appendChild(tree)
Deploy with the gh-pages command

您可以使用 gh-pages 模块将建成的网站推送到您的回购的gh-pages分支。

Note: if you're deploying a project at a basedir like username.github.io/project-name, you'll want to use the –basedir /project-name option

安装 gh-pages

npm install –save-dev gh-pages

创建一个 deploy npm脚本:

"scripts": {
  "deploy": "gh-pages -d dist"
}

发布您的网站:

npm run deploy

许可证

麻省理工学院




相关问题推荐