Would like to link to a different doc page

[morethanreal]

I would like to refer to a the docs for a different element (potentially in the same repository) from a doc page.

[atotic]

Me too!

[mbleigh]

Is there a reason not to just use full markdown links?

On Wed, May 27, 2015, 9:32 AM Aleksandar Totic notifications@github.com
wrote:

Assigned #34
#34 to @mbleigh
https://github.com/mbleigh.

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

[atotic]

How do we refer to docs for a different element? Will there be a canonical
url somewhere on polymer-project? Even then, there are multiple
versions.....

On Wed, May 27, 2015 at 9:55 AM, Michael Bleigh notifications@github.com
wrote:

Is there a reason not to just use full markdown links?

On Wed, May 27, 2015, 9:32 AM Aleksandar Totic notifications@github.com
wrote:

Assigned #34
#34 to
@mbleigh
https://github.com/mbleigh.

—
Reply to this email directly or view it on GitHub
<
#34 (comment)

.

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

[mbleigh]

Yes, there will be canonical urls. I think versioning is something to worry
about down the road

On Wed, May 27, 2015, 11:01 AM Aleksandar Totic notifications@github.com
wrote:

How do we refer to docs for a different element? Will there be a canonical
url somewhere on polymer-project? Even then, there are multiple
versions.....

On Wed, May 27, 2015 at 9:55 AM, Michael Bleigh notifications@github.com
wrote:

Is there a reason not to just use full markdown links?

On Wed, May 27, 2015, 9:32 AM Aleksandar Totic <notifications@github.com

wrote:

Assigned #34
#34 to
@mbleigh
https://github.com/mbleigh.

—
Reply to this email directly or view it on GitHub
<

#34 (comment)

.

—
Reply to this email directly or view it on GitHub
<
#34 (comment)

.

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

[arthurevans]

See also #9. I think the correct solution from a tool point of view is to allow the author to link to ArbitraryElement with some specific syntax, like ArbitraryElement or
{@link ArbitraryElement} and have hydrolysis/a doc merger script/some other tool resolve those links when you generate a batch of docs.

[notwaldorf]

I think this already works with markdown, both with absolute and relative paths (to the current element). See https://github.com/PolymerElements/iron-icon/blob/master/iron-icon.html#L55 for an example.

[arthurevans]

This kinda works now, but it works more or less by accident. It works because in the catalog, each element has a path like elements/foo-element... Provided that the element is the main element in a package. (You can't, for example, link to [paper-textarea](paper-textarea) and have it work, because the URL for that is elements/paper-input?active=paper-textarea.

You can embed the catalog-specific URL in your doc, but then you can't serve it statically, where the URL will be something like:

my-elements.html#iron-icons

And if you want to link to a specific property on a specific element, getouttatown.

So, my napkin-sketch of how this could work:

1. hydrolysis resolves {@link iron-input} or {@link iron-input#property-type} to a reference to a particular element or member and inserts (something) in the markup.

Or:

1a. We insert the (something) directly in the markup, in the form of, say, a special URL:

  [iron-input](api:iron-input)

2. iron-doc-viewer intercepts anchor clicks for api: URLs and fires an event.

3. iron-component-page or the router of choice receives that event, translates it to the URL scheme in use, and navigates to it.

[arthurevans]

I'm fine with this being a low priority for now but I do think we need to solve it eventually. Probably blocked by: PolymerElements/iron-component-page#57