# bisheng

> Transform Markdown(and other static files with transformers) into a SPA website using React.

Latest version **3.7.0-alpha.5** (published 2022-06-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install bisheng
pnpm add bisheng
yarn add bisheng
bun add bisheng
```

Provides the command `bisheng`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.7.0-alpha.5 |
| Published | 2022-06-14 |
| First published | 2016-05-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.6.0 |
| Dependencies | 49 |
| Unpacked size | 72.3 KB |
| Known vulnerabilities | 0 (+9 in 4 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2880 |
| Author | Benjy Cui |
| Maintainers | benjycui, afc163, paranoidjk, zombiej, ycjcl868, madccc |
| Keywords | markdown, spa, website, blog, react |

## Links

- npm: https://www.npmjs.com/package/bisheng
- Repository: https://github.com/benjycui/bisheng
- Homepage: https://github.com/benjycui/bisheng#readme
- Issues: https://github.com/benjycui/bisheng/issues
- npm.io page: https://npm.io/package/bisheng

## Dependencies (49)

- [less](https://npm.io/package/less.md) ^4.0.0
- [ramda](https://npm.io/package/ramda.md) ^0.26.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [history](https://npm.io/package/history.md) ^3.3.0
- [postcss](https://npm.io/package/postcss.md) ^8.4.13
- [prismjs](https://npm.io/package/prismjs.md) ^1.4.1
- [rc-util](https://npm.io/package/rc-util.md) ^5.20.0
- [resolve](https://npm.io/package/resolve.md) ^1.1.7
- [webpack](https://npm.io/package/webpack.md) ^4.25.1
- [exist.js](https://npm.io/package/exist.js.md) ^0.3.0
- [gh-pages](https://npm.io/package/gh-pages.md) ^2.1.1
- [nunjucks](https://npm.io/package/nunjucks.md) ^2.5.2
- [commander](https://npm.io/package/commander.md) ^4.0.1
- [jsonml.js](https://npm.io/package/jsonml.js.md) ^0.1.0
- [ts-loader](https://npm.io/package/ts-loader.md) ^6.2.1
- [css-loader](https://npm.io/package/css-loader.md) ^3.4.0
- [mark-twain](https://npm.io/package/mark-twain.md) ^2.0.0
- [url-loader](https://npm.io/package/url-loader.md) ^3.0.0
- [webpackbar](https://npm.io/package/webpackbar.md) ^4.0.0
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.0.0
- [less-loader](https://npm.io/package/less-loader.md) ^7.1.0
- [sass-loader](https://npm.io/package/sass-loader.md) ^8.0.0
- [autoprefixer](https://npm.io/package/autoprefixer.md) ^9.3.1
- [babel-loader](https://npm.io/package/babel-loader.md) ^8.0.0
- [loader-utils](https://npm.io/package/loader-utils.md) ^1.1.0
- [node-prismjs](https://npm.io/package/node-prismjs.md) ^0.1.0
- [react-helmet](https://npm.io/package/react-helmet.md) ^6.1.0
- [rucksack-css](https://npm.io/package/rucksack-css.md) ~1.0.2
- [style-loader](https://npm.io/package/style-loader.md) ^1.0.2
- [postcss-loader](https://npm.io/package/postcss-loader.md) ^4.3.0
- [@babel/polyfill](https://npm.io/package/@babel/polyfill.md) ^7.0.0
- [react-dev-utils](https://npm.io/package/react-dev-utils.md) ^4.1.0
- [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.0.0
- [nprogress-for-antd](https://npm.io/package/nprogress-for-antd.md) ^0.2.0
- [webpack-dev-server](https://npm.io/package/webpack-dev-server.md) ^3.11.2
- [@babel/preset-react](https://npm.io/package/@babel/preset-react.md) ^7.0.0
- [react-router-3-fork](https://npm.io/package/react-router-3-fork.md) ^3.2.6-rc.0
- [terser-webpack-plugin](https://npm.io/package/terser-webpack-plugin.md) ^1.1.0
- [jsonml-to-react-element](https://npm.io/package/jsonml-to-react-element.md) ^1.0.0
- [mini-css-extract-plugin](https://npm.io/package/mini-css-extract-plugin.md) ^1.4.1
- [friendly-errors-webpack-plugin](https://npm.io/package/friendly-errors-webpack-plugin.md) ^1.6.1
- [@babel/plugin-transform-runtime](https://npm.io/package/@babel/plugin-transform-runtime.md) ^7.2.0
- [babel-plugin-add-module-exports](https://npm.io/package/babel-plugin-add-module-exports.md) ~0.2.1
- [@babel/plugin-proposal-decorators](https://npm.io/package/@babel/plugin-proposal-decorators.md) ^7.0.0
- [case-sensitive-paths-webpack-plugin](https://npm.io/package/case-sensitive-paths-webpack-plugin.md) ^2.0.0
- [@babel/plugin-proposal-class-properties](https://npm.io/package/@babel/plugin-proposal-class-properties.md) ^7.0.0
- [@babel/plugin-proposal-object-rest-spread](https://npm.io/package/@babel/plugin-proposal-object-rest-spread.md) ^7.0.0
- [@babel/plugin-proposal-export-default-from](https://npm.io/package/@babel/plugin-proposal-export-default-from.md) ^7.0.0
- [@babel/plugin-proposal-export-namespace-from](https://npm.io/package/@babel/plugin-proposal-export-namespace-from.md) ^7.0.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 3.7.0-alpha.5 (latest) — 2022-06-14
- 3.5.0 (beta) — 2022-05-09
- 3.7.0-alpha.4 — 2022-06-10
- 3.7.0-alpha.3 — 2022-06-10
- 3.7.0-alpha.2 — 2022-06-10
- 4.0.0-alpha.0 — 2022-06-10
- 3.7.0-alpha.1 — 2022-06-10
- 3.7.0-alpha.0 — 2022-06-10
- 3.6.0 — 2022-06-09
- 3.5.0-alpha.1 — 2022-05-09
- 3.5.0-alpha.0 — 2022-05-07
- 3.4.0 — 2022-05-03
- 3.3.0 — 2022-04-25
- 3.2.1 — 2022-04-11
- 3.2.1-alpha.0 — 2022-04-11
- … 181 more at https://npm.io/package/bisheng/versions

## README

# Bi Sheng

[![](https://img.shields.io/travis/benjycui/bisheng.svg?style=flat-square)](https://travis-ci.org/benjycui/bisheng)
[![Build status](https://ci.appveyor.com/api/projects/status/lu5ut8vphqdfbxhi?svg=true)](https://ci.appveyor.com/project/benjycui/bisheng)
[![npm package](https://img.shields.io/npm/v/bisheng.svg?style=flat-square)](https://www.npmjs.org/package/bisheng)
[![NPM downloads](http://img.shields.io/npm/dm/bisheng.svg?style=flat-square)](https://npmjs.org/package/bisheng)
[![Dependency Status](https://david-dm.org/benjycui/bisheng.svg?style=flat-square)](https://david-dm.org/benjycui/bisheng)

> [Bi Sheng](https://en.wikipedia.org/wiki/Bi_Sheng) was the Chinese inventor of the first known movable type technology.

`bisheng` is designed to transform [Markdown](https://en.wikipedia.org/wiki/Markdown)(and other static files with transformers) into static websites and blogs using [React](https://facebook.github.io/react/).

## Sites built with BiSheng

* [A simple blog](http://benjycui.github.io/bisheng/)
* [Ant Design](http://ant.design)
* [Ant Motion](http://motion.ant.design)
* [Ant Design Mobile](http://mobile.ant.design/)
* [Ant Financial Design Platform](https://design.alipay.com/)
* [React AMap](https://elemefe.github.io/react-amap/articles/start)

You can create a PR to extend this list with your amazing website which is built with BiSheng.

## Features

`bisheng` is based on [dora](https://github.com/dora-js/dora) & [webpack](https://webpack.github.io/) & [React](https://facebook.github.io/react/) & [react-router](https://github.com/ReactTraining/react-router), and it has the following features:

* Support [`browserHistory`](https://github.com/ReactTraining/react-router/blob/v3/docs/API.md#browserhistory), even in [GitHub Pages](https://pages.github.com/).
* Lazy load for Markdown data.
* [Plugin](https://github.com/benjycui/bisheng/blob/master/docs/plugin.md) system to extend default behaviour.
* Server-side render for SEO.
* Support [`react-helmet`](https://github.com/nfl/react-helmet) for better SEO.

## Big picture

![Big picture of BiSheng](https://raw.githubusercontent.com/benjycui/bisheng/master/big-picture.jpg)

### Articles

* [bisheng-sourceCode-plugin](https://github.com/liangklfangl/bisheng-sourceCode-plugin)

## Usage

Installation:

```bash
npm install --save-dev bisheng
```

Then, add `start` to [npm scripts](https://docs.npmjs.com/misc/scripts):

```json
{
  "scripts": {
    "start": "bisheng start"
  }
}
```

Create `bisheng.config.js`, otherwise `bisheng` will use the default config:

```js
module.exports = {
  source: './posts',
  output: './_site',
  theme: './_theme',
  port: 8000,
};
```

**Note:** please make sure that `source` and `theme` exists, and `theme` should not be an empty directory. Just use [bisheng-theme-one](https://github.com/benjycui/bisheng/tree/master/packages/bisheng-theme-one), if you don't know how to develop a theme. See a simple demo [here](https://github.com/benjycui/bisheng/tree/master/packages/bisheng-example).

Now, just run `npm start`.

## Documentation

### CLI

We can install `bisheng` as a cli command and explore what it can do by `bisheng -h`. However, the recommended way to use `bisheng` is to install it as `devDependencies`.

```bash
$ npm install -g bisheng
$ bisheng -h
  Usage: bisheng [command] [options]

  Commands:

    start [options]     to start a server
    build [options]     to build and write static files to `config.output`
    gh-pages [options]  to deploy website to gh-pages
    help [cmd]          display help for [cmd]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
```

### Configuration

`bisheng` will read `bisheng.config.js` as its config file, but we can set the config file name by `--config`, something like this `bisheng --config another.config.js`.

The content of `bisheng.config.js` looks like this:

```js
module.exports = {
  port: 8000,
  source: './posts',
  output: './_site',
  theme: './_theme',
  htmlTemplate: path.join(__dirname, '../template.html'),
  devServerConfig: {},
  webpackConfig(config) {
    return config;
  },
  hash: false,

  entryName: 'index',
  root: '/',
};
```

#### port: Number

> default: 8000

To set the port which will be listened when we start a local server.

#### source: String | Array[String] | Object{ [category]: String | Array[String]}

> default: './posts'

To set directory/directories where we place Markdown files.

And all the Markdown files in `source` will be parsed and then structured as a tree data, for example:

```bash
posts
└── dir1
  ├── a.md
  └── b.md
```

Will output a **Markdown data tree**:

```js
{
  dir1: {
    a: {...},
    b: {...},
  },
}
```

And each Markdown file will be parsed as a **Markdown data**. Actually, a Markdown data is the returned value of [mark-twain](https://github.com/benjycui/mark-twain), and it could be preprocessed by plugins.

#### exclude: RegExp

> default: null

If you want to exclude some files in your `source`, just use `exclude`. Then bisheng will not parse files which match `exclude`.

#### output: String

> default: './_site'

To set directory where `bisheng` will generate (HTML & CSS & JavaScript) files to.

#### theme: String

> default: './_theme'

To set directory where we put the theme of website, and it also can be a npm package name.

[**More about theme**](https://github.com/benjycui/bisheng/tree/master/docs/theme.md).

* [bisheng-theme-one](https://github.com/benjycui/bisheng/tree/master/packages/bisheng-theme-one)

#### themeConfig: any

> undefined

A set of configuration that your theme provides, and then your theme can read it from `props.themeConfig`.

> Note: `themeConfig` will be `JSON.stringify` before it's passed to props, so you cannot pass function/RegExp through `themeConfig`.

#### htmlTemplate: String

> default: [`bisheng/lib/template.html`](https://github.com/benjycui/bisheng/blob/master/packages/bisheng/src/template.html)

The HTML template which will be use to generate HTML files which will be sent to users.

**Note:** template will be parsed by [nunjucks](https://mozilla.github.io/nunjucks/), and you can use the following variables in this template:

* [`root`](https://github.com/benjycui/bisheng#root-string)
* all attribute of [htmlTemplateExtraData](#htmltemplateextradata-object)

#### htmlTemplateExtraData: Object

> default: `{}`

The Extra Data which will be used to render [htmlTemplate](#htmltemplate-string).

#### devServerConfig: Object

> default: {}

You can consult [webpack-dev-server's documentation](https://webpack.js.org/configuration/dev-server/).

#### postcssConfig: Object

```js
default: {
    plugins: [
      rucksack(),
      autoprefixer({
        browsers: ['last 2 versions', 'Firefox ESR', '> 1%', 'ie >= 8', 'iOS >= 8', 'Android >= 4'],
      }),
    ],
  }
```


You can consult [webpack postcss-loader's documentation](https://webpack.js.org/loaders/postcss-loader/#options).

#### webpackConfig: (config) => config

> default: (config) => config

To modify the webpack config, you can extend the config like [this](https://github.com/ant-tool/atool-build#配置扩展).

#### transformers: Object[]

> [{ test: /\.md$/, use: [MarkdownTransformer](https://github.com/benjycui/bisheng/blob/master/packages/bisheng/src/transformers/markdown.js) }]

A list of transformers that will be used to transform static files.

#### entryName: String

> default: 'index'

The name of files which will be generated by webpack, such as `[entryName].js` & `[entryName].css`.

#### root: String

> default: '/'

If the website will be deployed under a sub-directory of a domain (something like `http://benjycui.github.io/bisheng-theme-one/`), we must set it (such as `/bisheng-theme-one/`).

## License

MIT

---
_Source: https://npm.io/package/bisheng · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._