Multiple Markdown Files

[Cody DeHaan]

It'd be great to be able to include several (or a whole folder of) .md files, and then have Flatdoc simply add them to the navigation on the left, so that a few .md files can be navigated (and several "guides" included in one interface).

[Dimitar Panov]

👍
This would really be a useful feature.

[P. Kerim Friedman]

Yes, I'd like to see this as well. I was able to get something along these lines working for Remark, but not sure how to adapt it for this:

https://github.com/gnab/remark/wiki/List-html-files

[Tamara Zuk]

👍 It might be a contradiction to the name but I, too, would find this useful. So far I have been using it to quickly whip up a nice interface to use internally for external libraries. A lot of scripts and plugins I use have their documentation separated into several .md files.

So far I have been creating separate html files for each and adding appropriate navigation to the header, but it becomes a pain to maintain very quickly.

[Sergio Vilar]

Hey guys, take a look at this:
https://github.com/sergiovilar/grunt-flatdoc

It's a grunt plugin to open with Flatdoc a folder that contains .md files

@rstacruz please take a look too! :)

[Cody DeHaan]

@sergiovilar Would love to see a demo project using the default flatdoc files + grunt-flatdoc. Not being that familiar with grunt, I didn't immediately see how to use this.

[Sergio Vilar]

Ok @codydh, I'll work on this!

[Hans Raaf]

I use this in the initialiser in the index.html to fetch multiple markdown files. This could be made more universal but it works good enough for me:

  <script>
    var combined='';

    Flatdoc.file = function(url) {
        return function(callback) {
            callback(null, combined);
        };
    };

    var get0=function() {
        url='00-Intro.md';
        $.get(url).fail(function(e) { alert("fail"); })
            .done(get1);
    };

    var get1=function(data) {
        combined+=data;
        url='01-First.md';
        $.get(url).fail(function(e) { alert("fail"); })
            .done(get2);
    };

    var get2=function(data) {
        combined+=data;
        url='02-Second.md';
        $.get(url).fail(function(e) { alert("fail"); })
                .done(getX);
    };

    var getX=function(data) {
        combined+=data;
        Flatdoc.run({
            fetcher: Flatdoc.file("")
        });
    };

    get0();

  </script>

[Gerben Jongerius]

A cleaner way for the loading of multiple files is probably:

      Flatdoc.file = function(locations) {
        function loadData(locations, response, callback) {
          if (locations.length === 0) callback(null, response);
          else $.get(locations.shift()).done(function (data) {
            loadData(locations, response + data, callback);
          }).fail(function(data) {
            callback(data, null)
          });
        }

        return function(callback) {
          loadData(locations instanceof Array ? locations : [locations], '', callback);
        }
      };

[Hans Raaf]

Yes, @gjong that is much nicer. What about creating a pull request for that?

[Vikram Rojo]

Found this grunt based flatdoc doc generator, haven't used it yet but it looks promising

https://github.com/equiet/grunt-bulldoc

[Austin McGee]

I've modified the Flatdoc.github fetcher to handle fetching a directory listing -- it will fetch all the markdown files in that directory and concatenate them. This keeps the API easy to use (see below).

Assuming I have a github repo with the following files:

- docs
  \- 01-intro.md
   - 02-main_documentation.md
   - 03-contributing.md
   - 04-license.md

and load the documentation in FlatDoc as follows:

Flatdoc.run({
      fetcher: Flatdoc.github('me/myrepo', 'docs')
});

Then flatdoc will fetch the directory listing for docs, then will fetch all of the markdown files in alphabetical order and concatenate them.

If other people want to use this I'll clean it up a bit, implement similar features for BitBucket and File fetchers, and need to add GitHub request caching (because it's now easier to go over the unauthenticated GitHub API rate limit), then open a PR.

Is this something people are interested in?

[Rico Sta. Cruz]

@gjong's fix adds support for Flatdoc.file([ 'file1.md', 'file2.md' ]) for now.

[Steve Bennett]

New user here. I was a bit surprised that fetching all markdown pages from a repo wasn't the default behaviour, so, yes, @amcgee, that's something I would be interested in. I went with @gjong's file-fetching workaround, though I fumbled around for a while not realising that the list has to be an array (as opposed to multiple arguments...)

[Austin McGee]

Cool, I'll open a PR

[P. Kerim Friedman]

@amcgee Did you get anywhere with this? Or does anyone know of other projects that are similar which have directory support?

[Rico Sta. Cruz]

May I interest you guys in docpress or gitbook instead? :-)

[suvilicious]

Hi all,

I've implemented a "Table of Contents" here. Requires TOC.md file to be present in the root folder.
It however does not work for GitHub repos because of the rate limit issue. If you need to, you can implement GitHub request caching as @amcgee mentioned above.

If you're serving this from GitHub Pages, then it'll work 100% fine in Flatdoc.file() mode.

• Repo. : https://github.com/lab25/crudadminlte/tree/gh-pages
• Demo : http://lab25.github.io/crudadminlte/

This implementation works well for what I need it for, so I probably won't be doing much more to it, but feel free to use it as you need 👍

[Cody DeHaan]

Didn’t get a chance to try it out yet, but scanning over it looks great to me!

On Jan 27, 2016, at 4:50 PM, Šimun Strukan [e-mail] wrote:

@codydh https://github.com/codydh I tried to do something like you described here https://github.com/Struki84/DocMapper, with php. Take look if it seems like a good idea, its deep in development, but i think its a cool prof of concept you described?

—
Reply to this email directly or view it on GitHub #15 (comment).