Each document block is treated as its own markdown document, should be each file.

[nickcarenza]

// Here is a [link][ref]

which is a thing.
then if I have my code next

angular.awesome()

and then because I think it looks nice I add the link ref at the bottom of the page

// [ref]: http://daringfireball.net/projects/markdown/syntax

The link doesn't work. It seems the blocks can't reference each other?

[keithamus]

This may be a regression of #100 @justindujardin created #112 which made a single call to showdown. Since then the markdown parser has been switched to marked, which still supports link references.

It looks like the single call situation is no longer the case. https://github.com/jashkenas/docco/blob/master/docco.js#L114-L122

[nickcarenza]

Is this functionality that others would find useful. I have code working to add this functionality. I modified the parse() function to check if the line is a ref using a custom regex /^[\s]*\[.*]: ?[\w\.\/:\-]* ?(".*")?$/. I tried utilizing marked.InlineLexer.rules but none of them seemed to match a ref by itself on a line. marked.InlineLexer.rules.reflink matched if a link using the ref [text][ref] was on a previous line but the parse function iterates through lines one at a time.

Inside parse() I defined a local variable refs and two methods isRef() and addRefs().

refs = [];

isRef() just tests the line against the regex I made

isRef = function(line) {
  return /^[\s]*\[.*]: ?[\w\.\/:\-]* ?(".*")?$/.test(line);
};

addRefs() goes through each section right before parse() returns the sections and adds each of the refs it found in the current file so that no matter where the reference was defined it will be available to all sections.

addRefs = function() {
  for(var _s = 0 ; _s < sections.length ; _s++) {
    for(var _r = 0 ; _r < refs.length ; _r++) {
      sections[_s].docsText += refs[_r] + '\n';
    }
  }
};

As you can tell I made the changes in docco.js instead of docco.litcoffee because I am not as comfortable in coffeescript but if the change is approved I would be more than happy to do it in the coffescript file.

I know that regex doesn't do a perfect job of matching urls. I am looking through marked.InlineLexer.rules to see if I can implement the one they use there.

[keithamus]

I think perhaps a simpler way to handle this would be to pass the entire document through marked once, rather than multiple times, just as it used to be after #112

[keithamus]

I'm going to kind of munge this issue with #227. Both issues relate to the same thing: Marked considers each doc block as a standalone markdown file. #227 is as follows:

---

I'm not sure how feasible this is, but it'd be really nice if one could do ordered lists across blocks of code in Docco. Currently if you do:

// 1. Foo
// 2. Bar

Markdown correctly translates that in to:

1. Foo
2. Bar

(formatted as an ordered list). However, if you try to mix code in:

// 1. Foo
var foo = 1;
// 2. Bar
var bar = 2;

you will get the code on the right, and on the left you'll see:

1. Foo
1. Bar

this makes sense in Markdown terms because if you do regular Markdown of:

1. Foo
 anything else
2. Bar

Markdown will consider that to be two separate lists, not one list broken up.

However, what that translates to in Docco terms is that one can never use a decimal point-based list to spell out steps. You can't use hashes either, eg.:

#1 Do X
#2 Do Y

because that gets formatted as a header. So the only option I can see for doing lists in Docco is to use a parenthesis:

1)
2)

and since that just produces <p> tags it's difficult to style such a list.

While I realize that this might be difficult to implement (since Docco relies on Markdown), lists are a very useful thing to have when creating documentation, so please consider providing some sort of solution for them.