Multiple Markdown Files

[codydh]

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).

[dpanov]

:thumbsup: This would really be a useful feature.

[kerim]

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

[tamarazuk]

:+1: 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.

[sergiopvilar]

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! :)

[codydh]

@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.

[sergiopvilar]

Ok @codydh, I'll work on this!

[oderwat]

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>

[gjong]

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);
        }
      };

[oderwat]

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

[vikramrojo]

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

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

[amcgee]

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?

[rstacruz]

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

[stevage]

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...)

[amcgee]

Cool, I'll open a PR

[kerim]

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

[rstacruz]

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

[ivus]

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 :+1:

[codydh]

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 notifications@github.com 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 https://github.com/rstacruz/flatdoc/issues/15#issuecomment-175874967.