Allow embedding anchors from docs

[xyeLz]

I've asked for this feature in so many platforms to date and have yet to see it successfully implemented. Basically, I'm looking for some way to embed anchors from one page into another. Here is my use case:

I often create pages of content that contain definitions. For example, "Business Impact Analysis" (BIA) and an associated definition. The BIA might appear in several topics. For example, it could appear within the "Business Continuity and Disaster Recovery" section and it could also appear within the "Business Operations" section. Additionally, I have an entirely separate section in the index aptly named "Terminology" where I also aggregate all of these "definitions." Rather than copy/pasting the text from one section to another, which also requires me to ensure the data is always kept up to date in all three locations instead of one, it would be unbelievable (and a complete differentiator from any other platform) if having the ability to embed anchors and the content contained within them existed. For example, being able to embed /exam/terminology/#business-impact-analysis into /exam/business-operations/ and /exam/bcdr/ by simply using an !embed command.

[geoffreymcgill]

Retype templates can do something similar to your requirements, although the content of the embed would be stored in a separate .md file.

You can include the content of another file from within the /_includes/ folder into any other page using the {{ include "file-name-here" }} template syntax.

For example, you can create a file at _includes/definitions/idea1.md with the following content:

- Item 1
- Item 2
- Item 3

Then include that idea.md snippet into another page using the following syntax:

# Sample page

## Definitions

{{ include "definitions/idea1" }}

The final generated page should look like the following:

The idea.md file could be included in any number of pages and each page will be generated with a copy of that content. This would allow you to maintain the content in one file in one location and that content would be included in all three of your pages.

Hope this helps.

[xyeLz]

Hey Geoffrey,

Thanks for commenting! This is a great feature but unfortunately wouldn't suit my needs since I'd ultimately need to create hundreds of .md files containing small amounts of information to embed. For example, terminology.md would contain hundreds of definitions. If I embedded this onto the cloud-computing.md page, it would embed all of the definition. Instead, I'd need to create individual pages containing any definition I wanted to embed, which would become unruly fast.

It may simply not be possible to embed specific anchors, but I figured I'd at least request it here and see if the capability could exist since it would be quite powerful!

[geoffreymcgill]

I believe we had this feature in a feature request issue when we were building the {{ include }} functionality, although I don't think it was built.

We also have a similar component for referencing code snippets using the following component, so adding functionality to reference just a text snippet could work in a similar manner.
https://retype.com/components/code-snippet/

This is something I can look into, although at the moment we have a lot of tasks on our TODO list and it's going to be tough to get too in the short term.

[geoffreymcgill]

Well, we did build similar include functionality but only to reference by line number(s), not by a content #anchor.

The following sample demonstrates including lines 18 to 26 of /exam/terminology.md into /exam/business-operations.md. Add the following line within your /exam/business-operations.md page.

{{ include "/exam/terminology.md#18-26" }}

You can include a single line number, a range of lines, or a mix of both:

{{ include "partial.md#1"  }}     // includes the 1st line only
{{ include "partial.md#1-5" }}    // includes a range of lines: 1-5
{{ include "partial.md#1,3-5" }}  // includes the 1st line and a range of lines: 3-5

Referencing by a named anchor would be nice and would certainly be easier to maintain as the content changes.

[xyeLz]

Oh man, even that is pretty awesome. But yes, being able to use the actual anchor in that page would make things much more scalable. It looks like you're most of the way there already so I will definitely keep my eyes on this one!

[xyeLz]

@geoffreymcgill I just tested this feature out with the line numbers (added some lines from /index/terminology.md to the "Quick Reference" section of my /concepts/auditing.md page) and it honestly worked perfectly. Can't believe you guys were able to build something like this! The only issue that's preventing me from using this is that using line numbers just simply isn't reliable. For example:

• If anyone makes a change to a page that throws the line numbers off, any of that included/embedded content is changed. It's not scalable.

• For many of your components, let's use panels as an example, on my terminology page I include all of my terminology in a single panel rather than multiple panels. It's easier and cleaner. But I can't use line numbers with these since, while I would accurately capture the ==- Definition, if that's not the last definition in the panel, I would also end up capturing the next definition in order to close the panel out.

While my original suggestion was to use anchors, I can certainly understand how this might be challenging, too. Do you include just the # anchor? Or do you include any ## and ### and #### anchors beneath it!? What if someone just wants a specific component (like a panel or a tab, or even as specific as part of a table)!? So many questions! I'm wondering if maybe you can build in a special character or characters like you have for other components (like !!! for alerts and ==- for a collapsed panel) that can include a header that can be used to encase any contents to include? Perhaps sort of like an anchor of its own? Although perhaps this would get unruly in the long run, too... In any case, I'm not sure the right answer, but this would be a very heavily used feature by me for not only my current project but also many future projects if you're able to make it work!

[geoffreymcgill]

We think we can build the following ///region component that would allow referring the region in another page.

///region definition1
The content for the definition would be here.
///endregion

The region requires a name, essentially an id, in the format of ///region <name> and must be on its own separate line.

To add that named ///region to another page, you would add use {{ include "/exam/terminology.md#definition1" }}. Whatever is between the ///region and ///endregion would be injected to the location of the {{ include }} call, including whitespace or blank lines above/below the content.

Thoughts?

[xyeLz]

That's a really good question! I suppose I'm not entirely sure without testing some sort of implementation. For example, could regions be included within panels? For example, let's say I wanted to capture the following definition on another page:

==- Word
Definition
==-

Could I use the region flag before the panel, such as:

///region MYNEWREGION ==- Word
Definition
==-///endregion

Or would I need to use it just for specific content, such as:

==- Word
///region MYNEWREGION Definition
///endregion

What if the region has the same name as the word/anchor?

///region Word ==- Word
Definition
==-///endregion

What if you wanted to include a region within a region?

///region North America # North America
This region includes many countries.

For example:

///region Canada ## Canada
///endregion
///region United States ## United States
///endregion
///endregion

I'm guessing this might not be possible unless the ///endregion is also specific to the start region.

I will say that I do like the potential flexibility of something like defining a region because instead of being stuck with a specific line number or anchor, I could be more granular. For example, maybe I wanted to use a collapsed panel on one page and an expanded panel on another page. That would be easy to do by simply defining the region outside of the impacted panel area (for example, not including ==- in the region and only including the relevant word and definition). I also fear the complexity of something like this. Again though, this is very specific to my use case so I'd surely be open to others' thoughts!

Sorry, not trying to overcomplicate things. Just getting my thoughts on paper!

[geoffreymcgill]

The Region component would be considered a block-level component and would require the opening ///region and closing ///endregion to each be on a separate line.

Your sample would be revised to the following:

///region MYNEWREGION
==- Word
Definition
==-
///endregion

If you only wanted the content of the Panel within the named region, you can reposition the region component to the following:

==- Word
///region MYNEWREGION
Definition
///endregion
==-

We haven't decided yet if nested regions would be supported, but it is likely they will be. Your sample would be revised to the following:

UPDATE The <name> of the region would essentially be an Id value, so spaces would not be supported. Your nested sample above would need to be revised to the following:

///region North-America
# North America
This region includes many countries.

For example:

///region Canada 
## Canada
///endregion
///region United-States 
## United States
///endregion
///endregion

Including the region would use the following {{ include }} component:

{{ include "/exam/terminology.md#United-States" }}

The <name> would be case-insensitive, so the following would work as well:

{{ include "/exam/terminology.md#united-states" }}

At least that is the proposal.