trulia / hologram

A markdown based documentation system for style guides.
http://trulia.github.io/hologram
Other
2.16k stars 199 forks source link

Add support for reference links to other components #171

Closed gpleiss closed 9 years ago

gpleiss commented 9 years ago

Our docs have lots of links to other components, e.g.:


---
title: Layout Lists
name: layout_lists
category: Layout

---

[Inline lists](/elements.html#list_inline) and
[vertical divider lists](/elements.html#list_vertical_divider)
are particularly useful when you don't know the width of the 
element you want to layout, or you want to vertically align it.

Use [Card lists](/elements.html#list_cards) if you'd like to make 
a grid of vertically and horizontally aligned cards.

These links are a little brittle, because we could change the name or the categories of the linked components, and then these links would be broken.

This PR adds the ability to use reference-style links between components, that follow the form [description of link][component_name]. These links even work for components in different categories. So the able example would become:

Sometimes you might want to use lists to lay out elements on the page.

[Inline lists][list_inline] and 
[vertical divider lists][list_vertical_divider]
are particularly useful when you don't know the width of the 
element you want to layout, or you want to vertically align it.

Use [Card lists][list_cards] if you'd like to make
a grid of vertically and horizontally aligned cards.

If a component belongs to multiple categories, the reference link will link to the first category. For example, if "list_inline" belongs to both the "Elements" and "CSS" categories, a reference link to "list_inline" would look like "/elements.html#list_inline".

If there is a reference link to a component that doesn't exist, hologram throws a warning.

cc/ @drpep @bebepeng @stubbornella

jdcantrell commented 9 years ago

This is pretty cool. Why did you choose [text][anchor] vs something more inline with markdown's current syntax for links?

gpleiss commented 9 years ago

The [text][component_name] syntax is the markdown syntax for reference links. We were toying around with other syntax such as [text](?name=component_name) or something like that, but reference links seemed to be the cleanest.

jdcantrell commented 9 years ago

I agree, I think reference one makes the most sense too, very good choice.

gpleiss commented 9 years ago

We moved the link_defs logic into the MarkdownRenderer - in the preprocess method. We inject the LinkHelper into the MarkdownRenderer :smiley:

gpleiss commented 9 years ago

What is the status on this PR?

jdcantrell commented 9 years ago

Oops, this dropped off my radar, merged it in, thanks for updating with the feedback :-)