GithubHelp home page GithubHelp logo

mdoc's Introduction

mdoc - a simple markdown based documentation generator

This is a simple markdown based documentation generator, it will search all the markdown files inside the "input" directory and output an HTML file for each document, it will also generate a "TOC" (table of contents) for each file and links to all the pages on the index page, it also provides a basic search feature and quick browsing between classes/methods/properties.

Reasoning behind it: inline documentation, why I'm ditching it .

Markdown syntax

mdoc uses the github "codeblock syntax" to highlight code. E.g.:

```js
  //code will be highlighted as JavaScript
```

```python
  //code will be highlighted as Python
```

Currently the parser considers H2 as sections/methods/properties names and will add them to the TOC at the top of each file and automatically generate deep-links to them. It's important to notice that mdoc only recognizes headers on the atx-style as a new section.

The first paragraph after the H2 will be used as description on the sidebar. Currently the search feature only searches copy from the title and description.

For a markdown syntax reference check: http://daringfireball.net/projects/markdown/dingus And also check the structure of the example files.

Install

You can install it through NPM:

npm install -g mdoc

Basic Usage

In a nodeJS file, create the basic outline with the desired configuration options listed below

require('mdoc').run({
    // configuration options (specified below)
    inputDir: 'docs',
    outputDir: 'dist'
});

Run the file node build.js. The outputDir will contain the finished HTML site.

Configuration

Source/Destination Directories (Required)

The following two options contain the source directory to read the documentation from and the destination directory to write the finished product to.

inputDir: 'docs'
outputDir: 'dist'

Basic settings (Optional)

Index File

These two options both specify what should go in to the index file. The indexContent setting will take precedence and overwrite anything specified in indexContentPath.

indexContentPath: 'path/to/index.md'
indexContent: '<h1>Custom markup to be inserted</h1>'

Site Title Tag

This controls what goes in the <title></title> tag in the outputted HTML. The format is Filename : WhatIsInbaseTitle.

baseTitle: 'mdocs title tag'

Advanced settings (Optional)

Custom Templates

Specify the path to the custom templates to use. These should be Handlebar template files

templatePath: 'path/to/template'

Static Assets

Specify the path to the static asset files (JS/CSS/images, etc)

assetsPath: 'path/to/assets'

Outputted File Names

Change the name of the outputted HTML files using a custom replacement string

mapOutName: function (outputName) {
 return outputName.replace('.html', '_doc.html');
}

Display Name

Change the name displayed on the sidebar and on the index TOC

mapTocName: function (fileName, tocObject, title) {
 return fileName.replace('_doc.html', '');
}

Include Files

Pattern that matches files that should be parsed

include: '*.mdown,*.md,*.markdown'

Exclude Files

Pattern that matches files that shouldn't be parsed

exclude: '.*'

Filter Files

Filters file. Return false to remove files and true to keep them

filterFiles: function (fileInfo) {
  return (/math/).test(fileInfo.input);
}

Heading Level

Sets which heading should be treated as a section start (and is used for TOC) defaults to 2

headingLevel: 3

Handlebars Helpers

You can also pass custom Handlebars helpers to be used during the compilation.

hbHelpers : {
  currency: function(val){
    var format = require('mout/number/currencyFormat');
    return format(val);
  },
  first: function(context, block) {
    return block.fn(context[0]);
  }
}

Handlebars context

You can also extend the context that gets provided to the Handlebars templates.

ctx : {
  version: '1.0.0'
  menu: [
    { name: 'Home', link: '/'},
    { name: 'Documentation', link: '/docs'},
    { name: 'API', link: '/docs/api'}
  ],
  site: {
    page: {
      title: 'API Documentation'
    }
  }
}

Those could be used inside your custom template as follow

<ul>
{{#each ctx.menu}}
  <li><a href="{{link}}">{{name}}</a></li>
{{/each}}
</ul>

<h2>{{ ctx.site.page.title }}</h2>

Also you can use Handlebars template in your markdown files:

## {{ ctx.site.page.title }}

Current version: {{ ctx.version }}

Parser override

If you want to use another markdown parser you can override the parsing function:

parsingFunction: function(markdownText): {
	return myParser.markdownToHtml(markdownText);
}

Examples

For a live example check: MOUT documentation or the unofficial NodeJS api (uses markdown files from nodejs repository as source)

Command line interface

mdoc -i examples/basic/content -o examples/basic/out

For a list of available commands run:

mdoc -h

Node module

Check files inside the "examples" folder. Run:

cd examples/basic
node build.js

Check output inside "examples/basic/doc".

Check "examples/advanced" for all the available settings.

License

Released under the MIT license.

mdoc's People

Contributors

annacruz avatar conradz avatar eddiemonge avatar johannjacobsohn avatar jourdain avatar kreozot avatar millermedeiros avatar prantlf avatar ruyadorno avatar tcort avatar tivie avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

mdoc's Issues

NPM version outdated

Seems that NPM repo points to v0.3.4 tag, which has been created in May, 2013. There has been several fixes and enhancement after that point (including hb helpers) so it would be really nice to add v.0.3.5 tag and bump version in NPM repository.

Nested output directories ruins links

Case 1 - flat dir:
outputDir: 'dist_docs'
Links looks like this: <li><a href="test1.html">test1</a></li>

Case 2 - nested dir:
outputDir: 'dist/docs'
Links looks like this: <li><a href="dist\docs\test1.html">test1</a></li>

So in second case links obviously doesn't resolves.

Page refresh and highlight the clicked item somehow

The refresh when I click on a category or an item is pretty distracting, also it would be cool to have some kind of highlight on the right when I click on an item on the left bar, because I dont wanna have to search for it every time on the right side.

Clicking on the toggling triangle in the sidebar index entry navigates to the article

Instead of expanding the index entry the click navigates to the page. It is annoying to be taken away from the current page when clicking on the toggling triangle. Apparently the triangle rendered by a CSS border trick "belongs" to the element so much, that a click on the border does the same as a click on the link text. The colour change on link hover confirms it:

problem

Also, the non-collapsible entries are pulled to the left side and appear "untidy".

If the triangle is applied to other element, clicking toggles without "danger":

fixed

Additionally, the left alignment of the non-collapsible entries could be fixed.

Tested with latest Chrome on Ubuntu.

convert style sheets to stylus

it will make it easier to customize colorscheme and since it is already a nodejs project it makes more sense to use stylus than other CSS pre-processors.

globals.converter._dispatch is not a function

Hi,

I've created a folder and added the examples\basic files to it and npm install mdoc. When I run node build.js I get the following errors:

$ node build.js
  Converting files...
C:\temp\node_modules\mdoc\node_modules\showdown\dist\showdown.js:1540
  text = globals.converter._dispatch('githubCodeBlocks.before', text, options);
                           ^

TypeError: globals.converter._dispatch is not a function
    at C:\temp\node_modules\mdoc\node_modules\showdown\dist\showdown.js:1540:28
    at makeHtml [as parseMdown] (C:\temp\node_modules\mdoc\node_modules\showdown\dist\showdown.js:881:50)
    at Parser.getDescription (C:\temp\node_modules\mdoc\src\js\parser.js:86:17)
    at Parser.getTocData (C:\temp\node_modules\mdoc\src\js\parser.js:61:31)
    at Parser.parseDoc (C:\temp\node_modules\mdoc\src\js\parser.js:19:20)
    at C:\temp\node_modules\mdoc\src\js\writter.js:85:43
    at Object.exports.processFile (C:\temp\node_modules\mdoc\src\js\pathProcessor.js:94:39)
    at C:\temp\node_modules\mdoc\src\js\writter.js:84:23
    at Array.forEach (native)
    at Writter.processDoc (C:\temp\node_modules\mdoc\src\js\writter.js:78:37)

I'm on Windows Server 2012 R2 64Bits with node v4.1.2.

Any thoughts on this?

thanks,
Bruno

load pages using Ajax

load pages using Ajax (if protocol isn't "file:") and use the HTML5 History API if available.

right now changing from one page to another isn't smooth since sidebar closes and opens again..

HTML Script-Tags in code blocks are being executed

When adding a script tag to the docs like this

```html
<script>console.log("this is a test")</script>
```\

it will be executed when opening the compiled docs in a browser.

image

Is this a bug or is there a way to stop this behaviour.

Escaping characters on sidebar

It happens that I had to document some of my internal methods, who uses underscores as a prefix.

For markdown parsing, I have to use a backslash when using underscore for starting a word, so all my h2 titles inside my md files starts like: ## _doSomething

The problem with this is that the backslash is being displayed on the sidebar menu for every method :( not beautiful at all.

I propose that we just remove any backslash from the sidebar menu, but I don't know if that might have deeper implications, some feedback on this would be appreciated, I can send a PR with the implementation.

Thanks!

Error running mdoc command

Hi, I installed the mdoc by: sudo npm install -g mdoc
and it installed properly but calling mdoc on terminal is returning this error:
env: node\r: No such file or directory

Any idea?

the installation finished with:

/usr/local/bin/mdoc -> /usr/local/lib/node_modules/mdoc/bin/mdoc
[email protected] /usr/local/lib/node_modules/mdoc
├── [email protected]
├── [email protected] ([email protected])
└── [email protected] ([email protected], [email protected])

And typing "which mdoc" it's point to /usr/local/bin/mdoc (what is correct)

I'm using:
Mac OS 10.7.5
node v0.8.11
npm 1.1.62

split TOC data from page content

there is probably no good reason for the TOC generation being inside the parser.js inside the method parseContent().. move it to the templates.

CLI not working

 →  mdoc
env: node\r: No such file or directory

Using node v4.1.0 in OSX v10.11. Not sure what's causing this.

add a new mode to concat all files inside a folder into a single file

create 2 different modes for documentation generation:

  1. treat each mdown file as a separate page. (current mode)
  2. aggregate all the files inside a folder into a single page with the same name as the folder. If a file with the same name already exists it would append the content to that file instead of creating a new file.

keyboard navigation

add keyboard navigation:

  • clear search + focus field.
  • jump to sidebar nav.
  • next / prev item on the sidebar.
  • open / close sidebar group.
  • select item.
  • toggle description.

add option to purge old files

delete all files inside the output folder before generating the documentation. it should prompt the user asking to confirm action.

Anchor links are not working without explicit path specification

Hello!

Thank you for this great library!

However, it looks like anchor links are not working without explicit path specification.

For example, I have this code in my index.md:

# Introduction

Also see [pagination](#pagination).

# Pagination

Most of the requests which return list of items support pagination.

When I try to compile it, I'm getting the error:

Could not parse metadata from /src/index.md
path.js:7
    throw new TypeError('Path must be a string. Received ' + inspect(path));
    ^

TypeError: Path must be a string. Received null
    at assertPath (path.js:7:11)
    at Object.extname (path.js:1433:5)
    at Renderer.renderer.link (.../node_modules/markdown-styles/lib/convert-md.js:58:22)
    at InlineLexer.outputLink (.../node_modules/markdown-styles/node_modules/marked/lib/marked.js:707:21)
    at InlineLexer.output (.../node_modules/markdown-styles/node_modules/marked/lib/marked.js:622:19)
    at Parser.tok (.../node_modules/markdown-styles/node_modules/marked/lib/marked.js:1075:50)
    at Parser.parse (.../node_modules/markdown-styles/node_modules/marked/lib/marked.js:935:17)
    at DestroyableTransform._transform (.../node_modules/markdown-styles/node_modules/markdown-stream-utils/lib/convert-md.js:11:28)
    at DestroyableTransform.Transform._read (.../node_modules/markdown-styles/node_modules/readable-stream/lib/_stream_transform.js:184:10)
    at DestroyableTransform.Transform._write (.../node_modules/markdown-styles/node_modules/readable-stream/lib/_stream_transform.js:172:12)

However, when I specify it like this: Also see [pagination](./#pagination)., it compiles correctly but leads out of index.html file to the root of the directory. The only working solution is to write it this way: Also see [pagination](./index.html#pagination)., but it's cumbersome and not very DRY.

Hardcoded "Table of Contents" link

Is better to move "Table of Contents" text to templates, because it is only one string, that can't be localized through templates.

parser.js:106

Convert .md links to .html when parsing

Hello,

Is there any way to change the links in the markdown files to the parsed files?
For example, my markdown file "Test" has a link to another file say: [link](link.md). This file Test on being converted to html has a link which points to link.md. I want it to point to link.html. Any way to do this??

Providing an extended context to handlebars for advanced template?

I'm currently investigating tools for documented our code base and mdoc seems to have everything that I care about. Except that I would love to provide an extended context to the handlebars templates.

The reason behind that is to generate a unique custom template across a various set of projects that belong to the same family while keeping some flexibility regarding some labels/lists/links/etc. And while we are getting helper access to handlebars, we are missing some control to the input context.

So I was wondering if I add a new optional entry into the configuration (ctx), would you be ok with that?Then I would simply add a ctx argument from the config.ctx to each compiled template.

Let me know if that seems reasonable, and if so, I'll do a pull request.

Thanks,

Seb

add --verbose option

and only log processed files if --verbose, otherwise just log number of files process and/or success/error message.

Backslashes on method names breaks TOC links

After working on issue #21, I just found out that my table of contents links is broken for any method starting with underscore, like: \_doSomething

The table of contents are linking to _doSomething and they need to actually link to \_doSomething in order to work.

It wasn't caused or related to issue #21 in any ways, it just happen to be the same use case causing different problems.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.