docpress / docpress-core

Parses projects and turns them into a documentation website

Docpress

Painless Markdown publishing

Documentation website generator.
Generates great websites from Markdown files.

Table of Contents

• What is it
• Examples
• Usage
• Support
• Thanks

What is it

Docpress generates websites from your project's basic documentation; that is, at the very least, a README.md file. It also supports multiple Markdown pages in docs/.

Under heavy development now; guides and instructions will magically appear here when we're stable.

Examples

Check out the Docpress Showcase to see how Docpress helped developers build great-looking websites.

Usage

Still under heavy development, consider this a preview. Requires Node v8+. See the Getting Started guide for more details.

$ npm install -g docpress
$ echo "# My project" > README.md
$ echo "Documented by Markdown files." >> README.md
$ docpress serve

  Docpress
  starting development - ^C to exit

  350ms ✓   first build                 
      on    watching changes
      on    livereload
      on    http://localhost:3000

  Running

Support

• Documentation
• Gitter chat

Let's build our first Docpress site. Quickstart guide →

Thanks

docpress © 2015+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz

docpress-core's Issues

Proposal: should missing local images links fail the build?

Currently they do....

However, GitHub supports linking to repo images in the README markdown files, like so:

# <img src="./icons/32x32.png"> Bathroom Status Chrome Extension (example)

However, this currently fails the build because of line 64 in fix_html.js

throw new Error(${base}: Unknown reference '${origUrl}')

What do you think about changing the fatal error to a console.error so that the docs still build. I'd rather have a broken image then no docs at all.

Side note:
I looked around the Metalsmith docs to see if there was a way of copying the local image to the build directory, but I didn't find anything solution.

Add favicon

In all sites that I run docpress favicon is missing!

What about add this functionality? 😄

Related: https://github.com/arccoza/metalsmith-favicons

Feature: adding an "ignore" option in docpress.json

When using docpress in a large code base it would be nice to tell the watcher to ignore certain directories. Not only can this improve the speed but it also fixes a problem I recently discovered where building the docs will not work because it's trying to reach inside of a electron app build.

Resolve relative path for assets

like:

"css": [
    "../node_modules/boostrap/dist/bootstrap.css"
]

Could be possible?

load custom JS

Docs says that is possible load custom CSS:

https://docpress.github.io/customization/css.html

What about load custom JS? Also could be nice select header or footer.

Publish version

We should probably publish a version, since the site is already updated and the bug fix.

Add sitemap

Just connect this ms plugin by default:

https://github.com/ExtraHop/metalsmith-sitemap

Add links support

This issue is related with the ability to directly refer link in the Table of Contents, instead of link a file.