Typedoc: Referencing External Pages

[Bruddles]

Hey,

I have a markdown file with examples in it, and i was wondering if there was any way to reference it in the documentation. I would like to keep the file separate from the code base where possible.

Thanks.

[sebastian-lenz]

Hi, nice to hear from you. Currently this is not possible but I see the point, something like this might be handy for long descriptions. Integrating something like this shouldn't be to complicated, we could expose a handlebars helper to do this. I'll have a look at this.

[mudHOAX]

:+1: I'd love to see this too.

[sebastian-lenz]

Okay, currently I'm implementing it this way:

• You can specify the location the external pages are located at with the argument
  --includes PATH/TO/INCLUDES
• Within your comments you can include files using
  [[include:PATH/TO/FILE]]
• If the included file is a handlebars template (*.hbs) it will be evaluated with the current reflection as its context

To be able to place images/documents I've also included the argument --media PATH/TO/MEDIA. This one must point to a directory and it will be copied to the output directory. One may specify references to files in this folder using media://PATH/TO/FILE and it will be resolved to a relative link pointing to the media directory.

[mudHOAX]

Great start, I really appreciate the work you're putting into this.

Would it be possible to further extend this to not only inline the external documents, but also provide a way to link to external documents and view them as a standalone entity.

For example we have a huge markdown file containing discussion and examples for a class as a whole. Whilst I appreciate I can inline this on the class, I'd prefer that the API for the class is still given top priority and having the ability to link over to a separate page completely for all the further discussion and examples.

[sebastian-lenz]

You can place the html file in the media directory and link to it using the media:// pattern. But I guess that's not what you are aiming for, you want the markdown file to be rendered using the documentation template?

This would be a great feature allowing you to include more detailed examples and guides within the documentation but it also raises a lot of questions and problems. How do you reach these docs, are they visible in the navigation, how are they named and sorted? I thought about giving TypeDoc the ability to load external plugins. Features like this one could be implemented as an optional plugin to TypeDoc.

[awerlang]

I think it'd be great if there's a way to have an index of all such external articles in front page like the one at (http://docs.sencha.com/extjs/4.2.3/#!/guide). Because there would be articles covering more than a single class, and would be nice to create a cross-reference system.

[kamranayub]

I was thinking about this yesterday. Similar to how msdn has a Remarks section, it would be great to be able to do this.

Even if there is a proper link feature, something like

@remarks

It could then take a folder to search for remarks and could match on fully qualified name. This would make it easy to maintain side by side docs without maintenance of updating comments.

This might be a separate feature but useful nonetheless.

[sebastian-lenz]

Do you mean the feature described here? If it resolves docs by qualified names, why do we need a comment tag?

[kamranayub]

It probably doesn't need to, you're right! I guess as long as it can be
organized into folders, it would suit our needs. Thinking that you could
also go one level deeper to the symbol, for examples and such, just like
MSDN.

On Mon, Apr 6, 2015, 13:21 Sebastian Lenz [email protected] wrote:

Do you mean the feature described here
https://msdn.microsoft.com/en-us/library/3zw4z1ys.aspx? If it resolves
docs by qualified names, why do we need a comment tag?

—
Reply to this email directly or view it on GitHub
https://github.com/sebastian-lenz/typedoc/issues/63#issuecomment-90035710
.

[SolarLiner]

How is this feature going? I have a TypeScript project in which I'd like to use Typedoc to generate guides besides the reference documentation, as it seems a much simpler solution than to build a whole documentation website just for the 3 guide files I'm going to put beside the reference documentation.

[Gerrit0]

Closing in favor of #247 - on the list... probably sometime next year.