Folder of markdown doc

[movrack]

Is it possible to include a folder of documents writted in markdown ?
A bit like githubs wiki to be able to write more files than only one readme big file.

[aciccarello]

Does #63 help at all?

[movrack]

It look to be a solution but I can't make it work.
I am on v 0.4.4.
I use this command line:

    typedoc -- --options typedoc.json --exclude '**/*.spec.ts' --exclude 'node_modules/**/*' --includes 'docs2/' ./app/

and docs2 contains 2 files
- demo1.md
- demo2.md

typedoc.json is:

{
  "name": "Mobile app",
  "mode": "modules",
  "out": "docs/",
  "theme": "default",
  "ignoreCompilerErrors": "true",
  "includeDeclarations": false,
  "experimentalDecorators": "true",
  "emitDecoratorMetadata": "true",
  "target": "ES5",
  "moduleResolution": "node",
  "preserveConstEnums": "true",
  "stripInternal": "true",
  "suppressExcessPropertyErrors": "true",
  "suppressImplicitAnyIndexErrors": "true",
  "module": "commonjs"
}

But I can't found demo1 or demo2 on generated doc in docs folder.

Moreover (it's an other error but probably a mess of my config), and because i am writting here all the conf, I always see theses "errors", that i want to exclude:
Error: /Users/.../node_modules/ionic-native/dist/plugins/webintent.d.ts(22) Cannot find name 'Promise'. Error: /Users/.../node_modules/rxjs/Observable.d.ts(9) Cannot find name 'Promise'.

[0815fox]

The doc states:

--includes <path/to/includes>
Specifies the location to look for included documents. One may use [[include:FILENAME]] in comments to include documents from this location.

So: do you refer to demo{1|2}.md somewhere in a tsdoc comment in one of your source files? e.g.

/**
 * [[include:demo1.md]]
 */

I did not use the feature myself, but that is what I would expect to work. This should then lead to demo1.md being searched and included into documentation. But maybe that is not even what you originally wanted? I understood it as if you wanted to integrate a complete doc structure, which - if I guess correctly - you want to be inserted e.g. in the navigation, so that you have typedoc and your documentation accessible in one place?

[movrack]

It's working, I can see the included content on the readme but it's I was expecting.
Here, if i includes all files, I will see all content on a big big big file to scroll on the first page.
I was more thinking about something like a link in on the website generated who can open the directory included. (for example in top right). And who can show md files.

And thee readme is also shown on the git repository first page but the [[include:demo1.md]] will not be shown on it.

[hayk94]

Guys were you able to make the includes work?

I try it like this with no success

here is how I run typedoc

"typedoc --out ./doc/ ./src --externalPattern '**/node_modules/**' --ignoreCompilerErrors --includes 'mdDocs/'"

in my mdDocs I have TypeScriptReactReduxTutorial.md so in my code file I do

// ./src/store/index.ts

/**
 * [[include:TypeScriptReactReduxTutorial.md]]
 */

import { combineReducers } from 'redux'

import { counterReducer } from './counter/reducer'

import { IApplicationState } from './types'

/**
 *  Whenever an action is dispatched, Redux will update each top-level application state property
 * using the reducer with the matching name. It's important that the names match exactly, and that
 * the reducer acts on the corresponding IApplicationState property type.
 */
export const rootReducer = combineReducers<IApplicationState>({
  counter: counterReducer
})

But nothing from my md file is being show in the generated docs only a line like this is being added

Defined in store/rootReducer.ts:18

[cuibonobo]

Including a MarkDown file by referencing it inside of my API documentation works for me. However, I think the original intent of this issue (and what I'm looking for as well) is to have a folder of MarkDown files that can be listed in the table of contents without being explicitly part of the API.

For example, if you wish to make the output of TypeDoc your complete documentation solution, you may want to include a page for architecture design, acknowledgements, etc. That information could go in the README, but for many projects it would be nice to split up into separate pages.

[reyalpsirc]

Any update on this? Will TypeDoc ever support a folder of Markdown docs together with the code generation?

[nadavhames]

A very hacky solution:
Make a .ts file with an empty module and put your markdown in the comments for that module.
Note that block comments in your markdown need to be converted to groups of single line comments.

/**
 * ## My Long Markdown File
 * Put your markdown here!
 * ```js 
 * //my
 * //block
 * //comment
 * ``` 
*/
namespace My_Guide {}

Credit goes to jaykaron for the find

[jaykaron]

Heres a quick script that converts Markdown files to one big TS file with empty namespaces.
It does not work if there are lists using * or block comments like /** ....

#!/bin/bash
# takes all the input files and places them within block comments
# on empty namespaces named the same as the filename (without the .md)
# and spits it out into stdout
# usage 'bash markdownToTs.sh *.md > someTsFile.ts'

while test $# -gt 0
do
    echo '/**'
    cat $1 
    echo '*/' 

    file_name=$1
    module_name=${file_name%???}    # remove .md ending
    echo "namespace $module_name {}"
    shift
done

For example for file test1.md:

# Test 1
- a 
- b
- c

it outputs:

/**
# Test 1
- a
- b
- c*/
namespace test1 {}

which is rendered as:

[mlzxy]

Another possible solution here:

1. fork https://github.com/TypeStrong/typedoc-site and put your markdown doc in its _guides folder
2. put your compiled typedoc output to api folder
3. customize it for your project and release the whole jekyll site

Not much extra work required but get a perfectly look and unhacky results.

[alexandercerutti]

Any news for a native way for this? This should be a must.

[Gerrit0]

This is next on my todo list once library mode (#1184) is done, but unfortunately I only have a couple hours a week to work on this project...

[mipatterson]

I wrote a TypeDoc plugin that I think might solve this need:
https://github.com/mipatterson/typedoc-plugin-pages
Live demo here

[dzek69]

@tony-scio and all others, this seems to work pretty well: https://www.npmjs.com/package/@knodes/typedoc-plugin-pages

it's not defined as a theme but as a plugin, which is nice, because it actually allows to use any theme with the tutorials addition

[JinYi2000]

yes, this works pretty well with 0.23.1: https://knodescommunity.github.io/typedoc-plugins/modules/_knodes_typedoc_plugin_pages.html

[transitive-bullshit]

https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/typedoc-plugin-markdown is another option that looks well maintained. I'm using it for one of my projects at the moment.

[josephearl]

I have extra markdown files in my repository like CHANGELOG.md and CONTRIBUTING.md that I'd like to have converted to HTML along with the README.md (and ideally have links between the .md files changed to work - e.g. when README.md links to CHANGELOG.md, when both are converted to HTML the link to the changelog should still work).

[Gerrit0]

This feature is coming to 0.26, which is available to try in beta now: 🎉 #2567