Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/f3rno/serve-markdown-it
Configurable static file server with markdown-it for parsing Markdown
https://github.com/f3rno/serve-markdown-it
cli configurable devtool markdown-it nodejs static-site-generator
Last synced: 22 days ago
JSON representation
Configurable static file server with markdown-it for parsing Markdown
- Host: GitHub
- URL: https://github.com/f3rno/serve-markdown-it
- Owner: f3rno
- License: mit
- Created: 2020-06-27T21:19:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-23T17:51:14.000Z (8 months ago)
- Last Synced: 2024-03-23T18:43:49.259Z (8 months ago)
- Topics: cli, configurable, devtool, markdown-it, nodejs, static-site-generator
- Language: JavaScript
- Homepage:
- Size: 907 KB
- Stars: 3
- Watchers: 2
- Forks: 3
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# serve-markdown-it - sermit
[![NPM Version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Downloads Stats][npm-downloads]][npm-url]
Configurable static file server with markdown-it for parsing Markdown.
> README & DOCS TODO
### [Installation](#installation)
```bash
yarn global add serve-markdown-it
```
### [Developing](#developing)
```bash
yarn gen-readme // update README.md
yarn docs // update DOCUMENTATION.md
yarn test // lint & mocha
yarn update-deps // bump all deps
```
### [Release History](#release_history)
See *[CHANGELOG.md](CHANGELOG.md)* for more information.
### [License](#license)
Distributed under the **MIT** license. See [LICENSE.md](LICENSE.md) for more information.
### [Contributing](#contributing)
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
---
## [API Reference](#api_reference)
> The standalone JSDoc reference can be found in [DOCUMENTATION.md](DOCUMENTATION.md)
## Modules
- serve-markdown-it
-
sermit -
serve-markdown-it.Description TODO.
Configurable static file server with markdown-it for parsing Markdown.
## Functions
-
getConfig(params) ⇒Promise -
Resolve the runtime configuration, loading the first user config file found.
Searches directories up the path for any of the following files:.sermitrc.sermitrc.js.sermitrc.json.sermitrc.yaml.sermitrc.yml
Any discovered user config file is merged with the default
DefaultConfig object. -
mergeConfig(params) ⇒Promise -
Overrides the default configuration with a user config object. Deep options
are replaced, shallow ones merged (i.e.markdown-itconstructor defaults). -
createServer(params) ⇒Promise -
Starts an HTTP server on the configured port, and serves static files out of
the specifiedbasePath. If thebasePathis a file, only that file will
be rendered, excluding any resolved assets.Files provided by the configured template are rendered from disk. Any URLs
ending in/rawhave the suffix removed and cause any matching file inbasePathto be rendered like an asset. This allows file contents to be
rendered with a link to the file itself.If a URL is not an asset or raw file, it is checked against the
matchMarkdownFileNamesregex on the provided Config object. Files
that match are passed throughmarkdown-it.Any remaining URLs are assumed to map to the
basePath; if they are files,
they are rendered as source within markdown code fences. Directories trigger
the file explorer if allowed by the configuration.
## serve-markdown-it
# sermit - `serve-markdown-it`.
Description TODO.
> Configurable static file server with markdown-it for parsing Markdown.
**License**: MIT
**Example** *(sermit help)*
```js
sermit [path] [options]
Serve local files
Commands:
sermit print-config Log the merged configuration to the console
sermit gen-config Generate a new configuration file
sermit render Render local files to static HTML
sermit serve [path] [options] Serve local files [default]
Options:
--log-level, -l Log level, increase to debug
[string] [choices: 'error', 'info', 'warn', 'debug'] [default: 'error']
--path, -p Root directory
[string] [required] [default: '/home/user/code/personal/serve-markdown-it']
--help Show help [boolean]
--version Show version number [boolean]
--port Port number to spawn HTTP server on
[number] [required] [default: 8960]
Examples:
sermit gen-config > .sermitrc.json Generate basic configuration
```
**Example** *(sermit)*
```js
[cli] › ★ star read config from /.sermitrc.json
[cli] › ★ star using template default
[cli] › ★ star using md plugin markdown-it-smartarrows
[cli] › ★ star using md plugin markdown-it-anchor
[cli] › ★ star using md plugin markdown-it-highlightjs
[cli] › ★ star serving content from /home/user/code/personal/serve-markdown-it
[cli] › ★ star listening at http://localhost:8960
```
**Example** *(sermit gen-config > .sermitrc.json)*
```js
{
minify: true,
excludeGitIgnore: true,
template: {
name: 'serve-markdown-it-template-default',
config: {
maxWidth: '960px',
sections: {
contentHeader: true,
settings: true,
debug: true,
content: true,
order: [
'settings',
'content',
'debug'
]
},
explorer: {
icons: true,
columns: [
'name',
'user',
'group',
'mode',
'type',
'size'
],
dataTable: {
searchable: true,
sortable: true,
perPage: 25,
perPageSelect: [
10,
25,
50,
100
],
fixedHeight: false,
layout: {
top: '{select}{search}',
bottom: '{pager}'
}
}
},
headerBar: false,
settingsBar: false,
dataTable: false
}
},
md: {
typographer: true,
linkify: true,
html: true,
plugins: [
{
name: 'markdown-it-smartarrows',
init: 'after',
config: {
auto: true,
code: true
}
},
{
name: 'markdown-it-anchor',
config: {
permalink: true,
permalinkBefore: true,
permalinkSymbol: '§'
},
init: 'after'
},
{
name: 'markdown-it-highlightjs',
config: {
auto: true,
code: true
},
init: 'after'
}
]
}
}
```
## getConfig(params) ⇒ Promise
Resolve the runtime configuration, loading the first user config file found.
Searches directories up the path for any of the following files:
- `.sermitrc`
- `.sermitrc.js`
- `.sermitrc.json`
- `.sermitrc.yaml`
- `.sermitrc.yml`
Any discovered user config file is merged with the default
[DefaultConfig](#Sermit..DefaultConfig) object.
**Kind**: global function
**Returns**: Promise - p - resolves with the final [Config](Config) object.
**Todo**
- [ ] consider including `basePath` in search
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| params | object | | params. |
| [params.basePath] | string | "cwd" | path to start searching in. |
| [params.configPath] | string | | path to pre-loaded user config file, required if `config` is provided. |
| [params.config] | object | | user config file if already found, search is skipped if provided. |
**Example**
```js
const config = await getConfig({ basePath: basePath })
const { state } = config
const { md, configPath, template } = state
if (configPath) {
l.star('read config from %s', colors.bgGreen.black(configPath))
}
if (_isEmpty(command) || command === 'serve' || command === 'render') {
l.star('using template %s', colors.cyan(template.name))
md.pluginNames.forEach((name) => {
l.star('using md plugin %s', colors.yellow(name))
})
}
```
## mergeConfig(params) ⇒ Promise
Overrides the default configuration with a user config object. Deep options
are replaced, shallow ones merged (i.e. `markdown-it` constructor defaults).
**Kind**: global function
**Returns**: Promise - p - resolves with final config object.
**See**: [getConfig](#getConfig)
| Param | Type | Description |
| --- | --- | --- |
| params | Array | `[userConfig, userConfigPath, basePath]` |
**Example** *(usage within getConfig)*
```js
const getConfig = ({ basePath, configPath, config: userConfig }) => (
(userConfig
? Bluebird.resolve({ config: userConfig, filepath: configPath })
: EXPLORER.search(basePath))
.then(({ config, filepath }) => [config, filepath, basePath])
.catch(() => [DEFAULT_CONFIG, null, basePath])
.then(mergeConfig)
.then(normalizeConfig)
.then(validateConfig)
.then(loadTemplate)
)
```
## createServer(params) ⇒ Promise
Starts an HTTP server on the configured port, and serves static files out of
the specified `basePath`. If the `basePath` is a file, only that file will
be rendered, excluding any resolved assets.
Files provided by the configured template are rendered from disk. Any URLs
ending in `/raw` have the suffix removed and cause any matching file in
`basePath` to be rendered like an asset. This allows file contents to be
rendered with a link to the file itself.
If a URL is not an asset or raw file, it is checked against the
`matchMarkdownFileNames` regex on the provided [Config](Config) object. Files
that match are passed through `markdown-it`.
Any remaining URLs are assumed to map to the `basePath`; if they are files,
they are rendered as source within markdown code fences. Directories trigger
the file explorer if allowed by the configuration.
**Kind**: global function
**Returns**: Promise - p - resolves to [koa](https://github.com/koajs/koa) instance.
| Param | Type | Description |
| --- | --- | --- |
| params | object | params. |
| params.basePath | string | absolute path to the root content directory. |
| params.config | Config | config data. |
**Example**
```js
const SERVE_HANDLER = async (argv) => {
const { l, port, config, path } = argv
const server = await createServer({ basePath: path, config })
server.listen(port)
l.star('serving content from %s', colors.underline(path))
l.star(
'%s',
colors.cyan.underline(
`listening at ${colors.bold(`http://localhost:${port}`)}`
)
)
}
```
[npm-image]: https://img.shields.io/npm/v/serve-markdown-it.svg?style=flat-square
[npm-url]: https://npmjs.org/package/serve-markdown-it
[npm-downloads]: https://img.shields.io/npm/dm/serve-markdown-it.svg?style=flat-square
[travis-image]: https://img.shields.io/travis/f3rno/serve-markdown-it/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/f3rno/serve-markdown-it