docpress / docpress Goto Github PK

View Code? Open in Web Editor NEW

888.0 16.0 80.0 796 KB

Documentation website generator

Home Page: http://docpress.github.io/

JavaScript 100.00%

docpress static-site markdown markdown-to-html documentation

docpress's Introduction

Docpress

Painless Markdown publishing

Documentation website generator.
Generates great websites from Markdown files.

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

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

Thanks

ricostacruz.com · GitHub @rstacruz · Twitter @rstacruz

docpress's People

Contributors

Stargazers

Watchers

Forkers

hunta01 daniel-xu kikobeats fahad19 knownasilya ellerbrock sincu carolineartz rwoll snailstudio samadmoizc8 muesliq beard01001 smithx10 richardneililagan tw-qt mrdanjl x-group johnstew guzuomuse kzap arrolin michaek justinfincher joyhooei ruslango zhouxiaokai alexanderisora ymatagne acidburn0zzz 5046312 codefork shawngregg gcamrit rap1ds matheweb e539238 idsingh emily0604 covertcode kruese tanbui kjantzer ahmedatefabd amuniweb liamstewart23 apirak urosnikolic virgo888 web3abhi omarisai noraj thisudoriguy zhao-junfeng ilya-lopukhin murindwaz lukejsonar thejpanganiban yupix ryanhs mdeboer feliex1992 crprinzler oflenake dmeister protw doc22940 ahmedbhl mucill qiokio rtmtfiallos maxbyz myjeffxie nishad khanbalarashidov nasingfaund ramosjsouza matthewwerny fang-zhang xdshack

docpress's Issues

Trying to use Docpress

Hello,
Preface, i'm a javascript noob and have almost never touched it. Given that i'm struggling on how to get the website rendering on github.
I can get the webpage rendering fine w/ docpress locally but when i push to github i instead get a plain markdown layout.
I'm definitely missing a file or configuration... i'm not sure, i'm kind of at a loss now. The github repo that i'm trying to get working is:
https://github.com/dborgesr/Euplotid
Thank you very much, i would appreciate any tips... i'm about to pull my hair out.

Set htmlhref language to site

My site is in Swedish but Google doesn't know that so I would specify this if hreflang. This doesn't seem possible. Would be great to set the language in docpress.json.

Rethink plugin config

Docpress is simply metalsmith with 2 plugins: docpress-core and docpress-base.

You can add plugins with the plugins configuration:

/* docpress.json */
"plugins": {
  "docpress-core": {},
  "docpress-base": {},
  "docpress-disqus": {}, /* hypothetical plugin */
  "docpress-edit-in-github": {} /* hypothetical plugin too */
}

This convention is not ideal. As a new user, my first instinct is just add docpress-disqus to the plugins list, but that's not the case. You need to repeat docpress-core and docpress-base in there.

My first instinct is to configure it this way because:

You may need to use something other than docpress-base, it should be easy to remove it
Some plugins may need to be before or after docpress-base (or -core), so it should be possible to do that

No idea what the best plugin API would be. Opening the discussion here on that.

(ps: @Kikobeats what's your npm email?)

disqus plugin

Let's support comments using disqus!

Just need to append extra HTML of bottom of doc pages:

https://kikobeats.disqus.com/admin/universalcode/

I think that this plugin is easy to write and useful, jut need a little of information about how to connect it with docpress core.

What do you think? @rstacruz knownasilya

Live code editing

Something like Vuep would be cool. Vuep is built on a static markdown site generator, and add live code snippets.

Mobile: Links should scroll down to content instead of index table.

For example, when a link from this index table is clicked in mobile, it redirects to that page, but still shows the index.

Instead, it should move to the start of the content.

Usually achieved by adding an id like '#header' to the 'Showcase' in above example, and making the links redirect to 'http://docpress.github.io/showcase.html#header' instead.

I'll make a pull request if I get time.

Thank you.

Missing/misnamed stylesheets?

Hi there, I'm excited for this project. I'm getting this error when I try to run docpress on a repo I'm working with (it has a readme and a docs/ folder).

  Docpress
  starting development - ^C to exit

   err ✗    first build
     ···    livereload
     ···    http://localhost:3000

            Starting up...

  ✗ /Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/docpress-base/data/style.styl:1:10
   1| @require './normalize.css/normalize.css'
    ✓ on    livereload
    ✓ on    http://localhost:3000                   n.css'
   3| @require './nprogress/nprogress.css'
            Running

failed to locate @require file ./normalize.css/normalize.css

    1| @require './normalize.css/normalize.css'
    ---------------^
    2| @require './github-markdown-css/github-markdown.css'
    3| @require './nprogress/nprogress.css'
    4| @require './iconfonts/stylesheets/ionicons'

    failed to locate @require file ./normalize.css/normalize.css

    at Evaluator.visitImport (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:901:21)
    at Evaluator.Visitor.visit (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/index.js:28:40)
    at Evaluator.visit (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:156:18)
    at Evaluator.visitRoot (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:693:27)
    at Evaluator.Visitor.visit (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/index.js:28:40)
    at Evaluator.visit (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:156:18)
    at Evaluator.evaluate (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:233:15)
    at Renderer.render (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/stylus/lib/renderer.js:86:26)
    at buildStylus (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/docpress-base/lib/build_css.js:37:7)
    at buildCss (/Users/sca/.nvm/versions/node/v5.0.0/lib/node_modules/docpress/node_modules/docpress-base/lib/build_css.js:8:3)

To repro, you can clone https://github.com/RoviSys/signal-arr-proxygen and try running docpress s inside the dir.

npm i -g docpress
git clone https://github.com/RoviSys/signal-arr-proxygen
cd signal-arr-proxygen
docpress s

Unknown reference '../README.md'

I keep getting this sort of errors: UnhandledPromiseRejectionWarning: Error: docs/releases/README.md: Unknown reference '../README.md'

I see a similar unanswered issue from a year ago (#233).

Here are the generated files and, as far as I can see, they are alright.

Opening the files with a MarkDown editor, I can navigate to all links with no issues.

I don't know what else I can do to make it work.

I'm on a Mac, if that's relevant, but the same issue happens on the GitLab-CI which runs on an instance of node:latest (docker).

Error: README.md: Unknown reference '/docs/components.md'

I've just cloned https://github.com/rstacruz/rscss and installed deps and ran npm run build.

windows 10. node 8.9.0

if i remove [Continue →](/docs/components.md) in the root README.md then it builds.

I get the same kind of error if I set the css in the config as such:

{
  "css": [
    "docs/theme.css"
  ],
  "markdown": {
    "plugins": {
      "decorate": {}
    }
  }
}

Search is not working in generated pages

Hi, Loving docpress so far.
Only one small issue, Search is not working in generated pages. Or what is the little spyglass upper left for?

How to set a domain for Automating GitHub pages ?

Everytime after commited, the CNAME file I created maually will be deleted.
How could I set a domain for documentation website ?

Favicon

In all sites that I run docpress favicon is missing!

What about add this functionality? 😄

travis build faild

First of all , I copy following string into my .travis.yml but build faild (the project is not a Node.js project)

# .travis.yml
node_js:
- 4

env:
  global:
    - GIT_NAME: Travis CI
    - GIT_EMAIL: [email protected]
    - GITHUB_REPO: rstacruz/myproject
    - GIT_SOURCE: _docpress

script:
- rake     # ...or whatever your test command is
- npm install docpress && ./node_modules/.bin/docpress build

after_success:
- if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]; then npm install git-update-ghpages && ./node_modules/.bin/git-update-ghpages -e; fi

Then build faild with following error:

Setting environment variables from repository settings
$ export GITHUB_TOKEN=[secure]
Setting environment variables from .travis.yml
$ export GIT_NAME=Travis
$ export [email protected]
$ export GITHUB_REPO=rstacruz/myproject
$ export GIT_SOURCE=_docpress
0.00s
rvm
0.11s$ rvm use default
Using /home/travis/.rvm/gems/ruby-1.9.3-p551
$ ruby --version
ruby 1.9.3p551 (2014-11-13 revision 48407) [x86_64-linux]
$ rvm --version
rvm 1.26.10 (latest-minor) by Wayne E. Seguin <[email protected]>, Michal Papis <[email protected]> [https://rvm.io/]
$ bundle --version
Bundler version 1.7.6
$ gem --version
2.4.5
50.61s$ npm install docpress && ./node_modules/.bin/docpress build
----\npm WARN engine [email protected]: wanted: {"iojs":">= 1.0.0","node":">= 0.12.0"} (current: {"node":"0.10.36","npm":"1.4.28"})
-/-\/npm WARN optional dep failed, continuing [email protected]
-----/--\||/-npm WARN deprecated [email protected]: this package has been reintegrated into npm and is now out of date with respect to npm
---/---\\\|\-\\\||//-\\\\|/|\\\\npm WARN engine [email protected]: wanted: {"node":">=0.12"} (current: {"node":"0.10.36","npm":"1.4.28"})
/|/-\\/\---/-|--|---|/\|/--\---\-[email protected] node_modules/docpress
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
└── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
/home/travis/build/EManual/docs/node_modules/docpress/bin/docpress:15
    docpress(cwd).build((err, res) => {
                                    ^
SyntaxError: Unexpected token >
    at Module._compile (module.js:439:25)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)
    at node.js:929:3
The command "npm install docpress && ./node_modules/.bin/docpress build" exited with 8.
Done. Your build exited with 1.

And once I add language: node_js in head of .travis.yml and it works.
So the document should add specify language in .travis.yml ?

subsites not included (windows)

I try docpress for the first time and I get a working version only with readme.md.

Example (README.md):

Homepage Name
=================

* [Homepage](/README.md)
* [Site1](site1/site1.md)

I always get
README.md: Unknown reference 'site1/site1.md'

The folder structure is:
-docpress
-README.md
--docs
--README.md
---site1
---site1.md

When I remove the line with site1 - everything works fine.

TOC not generating

I am not sure what the issue is, but I can't get it to generate the TOC as described in your usage instructions. I setup a super simple test over here: https://github.com/cvax/docpresstest
I am on docpress 0.7.0 and Windows 7.

When I serve this page it generates the root README.md just fine, but it doesn't build any of the TOC's README.md in /docs folder. I also tried to clone one of your showcase's docs to try serving, same result. Root README.md works, but TOCs didn't build.

Is this a docpress installation issue? Perhaps Windows issue? I just installed the npm package globally. There were some npm deprecated warnings on minimatch, native-or-bluebird, and fsevents though.

isso instead of disqus ..

would be a nice enh. for private docs/repos.

Cp. https://hub.docker.com/r/wonderfall/isso/

Mobile: 'Next' overlay shadows button

Here is an example.

This can usually be solved by adding a padding to the div. In my case,

<div class="body page-getting-startedquickstart" style="padding-bottom: 80px">
on page http://docpress.github.io/getting-started/quickstart.html helped.

I'll make a pull request if I get time.

Thank you.

How to get second heading to show in sidebar like on docpress site?

In your docs, for example, at

http://docpress.github.io/customization/markdown.html

in the sidebar I see the sub-headers in the sidebar with long dashed lines:

But on mine, I don't see the sub-headers:

I was expecting to see "HTML Buttons with Real Shadow" in the sidebar, but I don't see it. It is a second-level heading.

Docpress serve trips up on symlinked folder.

I've got some symlinked folders (that have nothing to do with the docs) which causes docpress to have some trouble:

  Docpress
  starting development - ^C to exit

   err ✗    first build
     ···    livereload
    ✓ on    livereload
    ✓ on    http://localhost:3000
            Starting up...
            Running
  ✗ Failed to read the file at: /home/trusktr/Downloads/src/trusktr+infamous/website/.meteor/local/dev_bundle

EISDIR: illegal operation on a directory, read

    EISDIR: illegal operation on a directory, read

This causes the serve mode not to work. Looks like symlinks to folders need to be ignored.

This indicates that docpress is watching files completely unrelated to the docs, which is probably likely to cause #229.

Google Analytics

Don't think my analytics is working correctly. Don't you need to also call:

ga('send', 'pageview');

Potentially with the URL path?

publish packages

Once #127 is merged, we should publish new versions of base, core and this module.

Link external URLs

Sometimes a need to reference a external URL from the sidebar.

For do that, basically I add this markup:

* [JS MythBusters](/README.md)
        * [Send your tip!](/send-tip.md)

when send-tip.md is just a empty file necessary for be compiled by docpress, and later using JS I change the href of the URL generated.

Could be nice support URL's directly from Docpress.

Comparison to Gitbook?

So I stumbled upon this by reading over http://rscss.io/. Nice work btw! When I looked at rscss/gh-pages I saw docpress, so here I am.

The number one question on my mind is how is this different than Gitbook. So it'd be cool if you'd update the readme or add a FAQ or something. Maybe you already have and I missed it, thanks. But it looks awesome!

Indexer chokes on symbolic links

→ sean@magic-box | ~/Projects/dabble | branch: develop *+ | battery: 99% | load: 0.27 
λ DEBUG='*' npm-exec docpress
  docpress-core Using config: /home/sean/Projects/dabble/docpress.json +0ms

  Docpress                                          
  starting development - ^C to exit                 

   err ✗    first build                             
     ···    livereload                              
     ···    http://localhost:3000                   

            Starting up...                          
    ✓ on    livereload                              
  ✗ Failed to read the file at: /home/sean/Projects/dabble/include/python2.7

EISDIR: illegal operation on a directory, read  

    EISDIR: illegal operation on a directory, read  
    at Error (native)                               
    ✓ on    http://localhost:3000                   
  tinylr:server Configuring HTTP server +0ms
            Running                                 
  connect:dispatcher use / anonymous +1ms
  router use / <anonymous> +0ms
  router:layer new / +0ms
  router use / <anonymous> +9ms
  router:layer new / +0ms
  connect:dispatcher use / anonymous +12ms
^C^X
→ sean@magic-box | ~/Projects/dabble | branch: develop *+ | battery: 99% | load: 0.24 
λ stat include/python2.7
  File: ‘include/python2.7’ -> ‘/usr/include/python2.7’
  Size: 22          Blocks: 8          IO Block: 4096   symbolic link
Device: 15h/21d Inode: 2968562     Links: 1
Access: (0777/lrwxrwxrwx)  Uid: ( 1000/    sean)   Gid: ( 1000/    sean)
Access: 2016-07-20 15:30:44.736296965 -0500
Modify: 2016-07-20 15:22:03.308303091 -0500
Change: 2016-07-20 15:22:03.308303091 -0500
 Birth: -

At this point, no pages have been generated but it starts the router and serves anyway.

How to insert an image?

![Work together and collaborate](images/work-together-and-collaborate.png)

When I try to add the image, got this error.

(node:5648) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 46): Error: README.md: Unknown reference 'images/work-together-and-collaborate.png'

TypeError: Cannot read property 'contents' of undefined

C:\work\zweb-doc\node_modules\docpress-base\index.js:134
if (!file.contents) return
^

TypeError: Cannot read property 'contents' of undefined
at scripts.map (C:\work\zweb-doc\node_modules\docpress-base\index.js:134:21)
at Array.map ()
at callback (C:\work\zweb-doc\node_modules\docpress-base\index.js:128:33)
at C:\work\zweb-doc\node_modules\browserify\index.js:779:13
at ConcatStream. (C:\work\zweb-doc\node_modules\concat-stream\index.js:36:43)
at ConcatStream.emit (events.js:187:15)
at finishMaybe (C:\work\zweb-doc\node_modules\concat-stream\node_modules\readable-stream\lib_stream_writable.js:475:14)
at endWritable (C:\work\zweb-doc\node_modules\concat-stream\node_modules\readable-stream\lib_stream_writable.js:485:3)
at ConcatStream.Writable.end (C:\work\zweb-doc\node_modules\concat-stream\node_modules\readable-stream\lib_stream_writable.js:455:41)
at Readable.onend (C:\work\zweb-doc\node_modules\readable-stream\lib_stream_readable.js:577:10)

Disabling loading pages via XHR

First of all, many many thanks for this awesome project! It looks so beautiful, I couldn't resist myself from using it for a new project of mine. Really well done!

The issue

I came across a very rare issue. When there are links for the same domain, but not of the docs itself, there is an XHR failure, and the UI keeps on loading.

Real life example

For example, in this page https://fahad19.github.io/tydel/examples/counter/index.html, if you click on Source, it will not load.

The docs are hosted in https://fahad19.github.io/tydel/, and I am trying to link to https://fahad19.github.io/tydel-demos/. GitHub Pages of two separate repos.

Possible solution

I believe, if the linked URL does not start with https://fahad19.github.io/tydel/ (with an ending slash), we should not try to load it via XHR and just go to that URL directly.

Set livereload-port for docker watch to work

It's be great if watch mode in docker would work.

to make this happen, you need to allow setting the live-reload port from docpress, otherwise get-port will choose a random port every time, which isn't feasible for docker-compose.

version: "2.1"

services:

  frontend:
    image: my-image-name
    ports:
      - 3000:3000
    environment:
      - PORT=3000
      - HOST=0.0.0.0
      - CHOKIDAR_USEPOLLING=true
    working_dir: /opt/app/
    command: npm run serve
    volumes:
      - ./package.json:/opt/app/package.json
      - ./docs:/opt/app/docs
      - ./README.md:/opt/app/README.md
      - /opt/app/node_modules

[Feature] Edit this page

Have a button that takes the user directly to the markdown for the page they want to edit.
This could be done by specifying the url of the docs folder in the config.

This project is awesome, what are your plans?

Hi,

I really like the work you've put into this project. I've been wanting for something like this for long! I like the theme and everything in this project. What are your plans in with this project? It seems that you are not very actively developing it anymore. Have you found another tool which does the same job?

Docpress local install funk

Description

I'm trying to use docpress in my project, however, I've run into a weird issue with installing it locally in my project. After installing it globally (npm install docpress -g) everything works fine. After installing it locally (npm install docpress --save-dev), however, when running it, it exits immediately, producing no output.

Versions of my stuff

OS: Windows 10
node: 4.1.1
npm: 3.5.0
docpress: 0.6.6

Steps

git clone https://github.com/1vasari/docpress-issue
cd docpress-issue
npm i
docpress s

Note: removing node_modules makes it work again. Putting them back breaks it.

Handle mail address

Hi again,

Maybe a issue with a mail address in mardown file.

Input

...contacting a project maintainer at [email protected].

Output

✗ readme.md: Unknown reference '[email protected]'

ENOSPC error. Not sure why.

I'm not sure why yet, but trying to use docpress is giving me a Node error ENOSPC which seems to be related to file watching. This is the stack:

Error: watch /home/trusktr/Downloads/src/trusktr+infamous/.docpress ENOSPC
    at _errnoException (util.js:1026:11)
    at FSWatcher.start (fs.js:1383:19)
    at Object.fs.watch (fs.js:1409:11)
    at createFsWatchInstance (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:37:15)
    at setFsWatchListener (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:80:15)
    at FSWatcher.NodeFsHandler._watchWithNodeFs (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:228:14)
    at FSWatcher.NodeFsHandler._handleDir (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:407:19)
    at FSWatcher.<anonymous> (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:455:19)
    at FSWatcher.<anonymous> (/home/trusktr/Downloads/src/trusktr+infamous/node_modules/metalsmith-start/node_modules/chokidar/lib/nodefs-handler.js:460:16)
    at FSReqWrap.oncomplete (fs.js:154:5)

It happens only with the serve command, but the build command works just fine.

I could probably post a reproduction repo, but you'll probably not get the error. I'm on a little Chromebook. Any thoughts or suggestions on what to try?

Support for Multiple Languages

What is the best way to support multiple languages? I refer to programming languages.

I am working on a documentation site where I would like to provide snippet in multiple languages for a given question..

How can I organize the content to offer such content?

Rename docpress-base → docpress-html

To do:

Rename GitHub repository
Publish docpress-html as a new version
Publish new Docpress version using the new package name
Add an npm deprecate notice to docpress-base
Update references to docpress-base in docpress's code
Update any relevant docs (#144)

CRASH: TypeError: Cannot set property 'contents' of undefined

If I try to setup docpress, I keep getting this crash:

/path/to/project/node_modules/docpress/bin/docpress:16
      if (err) throw err
               ^

TypeError: Cannot set property 'contents' of undefined
    at eachCons (/path/to/project/node_modules/docpress-base/index.js:219:19)
    at keys.forEach (/path/to/project/node_modules/docpress-base/lib/helpers/each_cons.js:11:5)
    at Array.forEach (<anonymous>)
    at eachCons (/path/to/project/node_modules/docpress-base/lib/helpers/each_cons.js:8:8)
    at Object.relayout (/path/to/project/node_modules/docpress-base/index.js:197:3)
    at Ware.<anonymous> (/path/to/project/node_modules/wrap-fn/index.js:45:19)
    at next (/path/to/project/node_modules/ware/lib/index.js:85:20)
    at /path/to/project/node_modules/wrap-fn/index.js:121:18
    at callback (/path/to/project/node_modules/docpress-base/index.js:104:5)
    at useCache (/path/to/project/node_modules/docpress-base/lib/helpers/use_cache.js:6:5)

Project in question: https://github.com/ConnectedHumber/Air-Quality-Web/tree/new-docs (don't forget to checkout the new-docs branch).

Commands used:

npm install
node_modules/docpress/bin/docpress build

How manage ./contributing.md, ./history.md, etc?

Hi,

I try to add docpress on a existing project.
But in the ./readme.md some link point to root directory for contributing.md or history.md

Example:

./readme.md

...
*Read our [contributing guide](contributing.md) if you're looking to contribute (issues/PRs/etc).*
...

output `docpress s`

err ✗  ↔ readme.md                               

  ✗ readme.md: Unknown reference 'contributing.md'

docpress init

There should be a docpress init command to build a default skeleton.

├── docs
│   ├── example.md
│   └── README.md
├── .gitignore
└── README.md

Where README.md can be the actual docpress readme or a bootstrap, .gitignore the actual docpress gitignore, docs/README.md a short TOC and docs/example.md a markdown cheat sheet or a bootstrap.

docs/README.md

* [docpress](../README.md)
* [Example](example.md

Embedded examples don't load

I have some codepen examples I embed into my documentation, and they'll load on a browser refresh, but not when clicking from one page to the next. I changed the "DOMContentLoaded" listener to "load" instead, and that fixed it, but maybe there's a better way.

How to get markdown plugins working?

Nice job on this project!

I'm trying to follow the docs on getting a markdown plugin working. For example, I tried installing markdown-it-emoji just like the docs said, then I tried putting :smile: in my markdown, but it just renders :smile: rather than 😄 .

My package.json has this:

  "docpress": {
    "docs": "src", // my API docs are co-located with source files
    "dist": ".docpress",
    "github": "trusktr/infamous",
    "markdown": {
      "emoji": {}
    }
  },

and I installed it, npm i markdown-it-emoji --save-dev --save-exact.

Any idea why do smiley's not appear?

Does Docpress support non-public repos?

Is there a possibility to authenticate with Github, to display repos that are private?

URL of image file is broken

When Markdown file and image file are placed in subdirectory, Images may not be displayed.

This problem disappears when reloading with the web browser. Docpress seems to have generated a relative URL from the previous page.

I made a demonstration.
miyahan/docpress-bug-demo

Am I using the wrong way? Or is this a bug?

Best way to add custom header/footer HTML?

Was wondering if there is an easy way to add a custom header or footer to each page, for example.

EMFILE: too many open files

It seems to get caught up because I have extra node_modules installed in a subdirectory (It's a Yeoman generator. It needs its own modules, and any modules used by the generated project for testing purposes)

MINGW64 $ docpress s

  Docpress
  starting development - ^C to exit

    first build
aNA       livereload
aNA       http://localhost:3000
aNA
    Starting up...
aNA   aNA
  ✗ Failed to read the file at: C:\Users\<user>\Documents\generator-angular-fullstack\test\fixtures\node_modules\gulp-typings\node_modules\delayed-stream\Readme.md

EMFILE: too many open files, open 'C:\Users\<user>\Documents\generator-angular-fullstack\test\fixtures\node_modules\gulp-typings\node_modules\delayed-stream\Readme.md'

    EMFILE: too many open files, open 'C:\Users\<user>\Documents\generator-angular-fullstack\test\fixtures\node_modules\gulp-typings\node_modules\delayed-stream\Readme.md'
    at Error (native)

aNA   aNA   aNA            Running                                 aNB

The TOC does not support Chinese?

Update docpress-core deps to fix security issue.

Docpress-core was recently updated with a security vulnerability fix:

docpress/docpress-core@3cc193c

Please update the docpress repo to use the updated docpress-core.

failed to locate @require file ./normalize.css/normalize.css

Do I need to do anything to use stylus?

No error if using css. Error if do.

docpress.json:

{
  "markdown": {
    "plugins": {
      "decorate": {}
    }
  },
  "css": [
    "docs/style.styl"
  ]
}

Error:

  ✗ /Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/data/style.styl:1:10
   1| @require './normalize.css/normalize.css'
---------------^
   2| @require './github-markdown-css/github-markdown.css'
   3| @require './nprogress/nprogress.css'
   4| @require './iconfonts/stylesheets/ionicons'

failed to locate @require file ./normalize.css/normalize.css

    1| @require './normalize.css/normalize.css'     
    ---------------^                                
    2| @require './github-markdown-css/github-markdown.css'  
    3| @require './nprogress/nprogress.css'         
    4| @require './iconfonts/stylesheets/ionicons'  

    failed to locate @require file ./normalize.css/normalize.css  

    at Evaluator.visitImport (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:901:21)  
    at Evaluator.Visitor.visit (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/index.js:28:40)  
    at Evaluator.visit (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:156:18)  
    at Evaluator.visitRoot (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:693:27)  
    at Evaluator.Visitor.visit (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/index.js:28:40)  
    at Evaluator.visit (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:156:18)  
    at Evaluator.evaluate (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/visitor/evaluator.js:233:15)  
    at Renderer.render (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/stylus/lib/renderer.js:86:26)  
    at buildStylus (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/lib/build_css.js:37:7)  
    at buildCss (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/lib/build_css.js:8:3)  
    at Object.addCss (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/index.js:107:5)  
    at Ware.<anonymous> (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/wrap-fn/index.js:45:19)  
    at next (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/ware/lib/index.js:85:20)  
    at /Users/john/dev/docsites/felix/node_modules/docpress/node_modules/wrap-fn/index.js:121:18  
    at callback (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/index.js:120:5)  
    at useCache (/Users/john/dev/docsites/felix/node_modules/docpress/node_modules/docpress-base/lib/helpers/use_cache.js:6:5)

docpress --help vs docpress -h

The help message seems quite empty.

$ docpress --help
Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

But in fact --help is not an alias of -h even if it is what it is written.

$ docpress -h    

  Documentation website builder

  Usage:
    docpress [command] [options]

  Commands:
    serve             starts a server (default)
    build             builds files

  Options:
    -h, --help        show usage information
    -v, --version     print version info and exit

Roadmap

Here's a tentative roadmap.

v0.7 — Just cleanups.
v0.8 — Theming; finalize plugin system.
v0.9 — Extract things into plugins (docpress-disqus, docpress-google-analytics).

Road to v1

And criteria for a v1 release:

Theming should be easy. Designers shouldn't have to be hassled just to make something nice; just fork docpress-theme-light (or whatever) and edit along.
There should be at least 2 "official" themes. docpress-rsc will be made into an actual theme (ie, a docpress plugin), and it should be a good starting point for people wanting to make themes. Other candidates would be a one page theme and a monospace theme.
Mobile should be fully taken care of. There should be a mobile sidebar toggle.
The default theme should be spruced up a bit and made nicer... something we'd be happy to stick around for a long time.

Missing dependency

Hi, when running this locally I encounter the following issue:

Failed to read the file at: ...../node_modules/.bin/mkdirp
ENOENT: no such file or directory, stat '..../node_modules/.bin/mkdirp'

I'm running docpress locally:

$ npm i docpress --save-dev
$ node_modules/.bin/docpress serve

Manually installing the mkdirp package seems to cure the issue for me.