Markdown Document Navigation

Looker Q&A Looker
1

I wasn’t able to find good documentation on this, so thought I’d make a post here in case anyone is trying to do something similar.

You can create a navigation sidebar for Markdown documents using this format at the top of each Markdown document:

---
title: Help Center
navigation:
  - section: Help Center
  - document: overview_doc
    label: Overview
  - document: data_sources_doc
    label: Data Sources
  - document: data_definitions_doc
    label: Data Definitions
  - document: faq_doc
    label: FAQ
  - document: release_notes_doc
    label: Release Notes
---

And it will appear as a sidebar like this:

markdown_sidebar.png
markdown_sidebar.png200×248 4.5 KB

Users can get there from any dashboard by clicking a Help link at the top of every page. We created that link by adding a text tile with HTML at the top of each page:

  - name: Help Link
    type: text
    title_text: "<a href='/projects/model/documents/overview_doc.md' ><i class='fa fa-question-circle' aria-hidden='true'></i> Help</a>"

And it looks like this:

help_link.png

The icon comes from the Font Awesome library.

Hope this is helpful to someone!

9 Likes
2

This is great stuff. I just thought I should drop a link back to an old question that was posted on discourse regarding markdown document navigation. Check it out at Adding Markdown Document to a Dashboard.

3 Likes
3

Thanks for this, I have been searching around for this syntax and it isn’t anywhere online!
I am struggling setting the document to a location other than the current path (I am spreading my documentation out across the projects in which the documentation refers).
Anywhere I can do some more reading or any help greatly appreciated.

1 Like
4

I’ve been trying to figure this one out with the help of a few others, and I can’t find much more than you. Our docs do have this: https://docs.looker.com/data-modeling/getting-started/other-project-files#adding_a_navigation_structure_to_your_documentation which explains the use of the syntax, but don’t shed light on how to reference another project.

We are on the hunt internally, and we’ll definitely figure it out one way or the other. Stay tuned.

5

It looks like it’s not currently possible to reference documents from other projects— Worth opening a feature request for! I suppose you could add literal links to get there, but it won’t mesh as nicely.

6

I am far from even a rookie with html/css/md but something seems off. This page suggests that the css tag of “float” is ok, yet on a md document page I cant get anything to stick to either side (I am making my own navigation panel). It just puts everything into the middle of the page. I can hack it around so that it pushes it to the left by putting stuff on the right of it but this is going to mess up with different screen sizes and is far from consistent.
Anyone offer any help here?

1 Like
7

That docs page specifically references which parameters are allowed in the html parameters— I think the dashboard text is actually “Github Flavored Markdown”, which includes some but not all the functionality of HTML.

I wonder if markdown just doesn’t support the use of those kinds of tags? That seems unlikely to me.

Getting this some visibility from those who know just what Looker’s markdown is capable of…

8

Hi, any news on this one?

1 Like
9

I did some research but similarly couldn’t figure it out, waiting on the engineers who created our markdown implementation to get back to me. I won’t forget to update this thread.

1 Like
10

Any info about this, wanting to implement this dispersed home page where each team looks after their own page from their own projects but I own the central page. Cant use the navigation function the OP posted about but wishing to create my own navigation…stuck to the left side of the page.

1 Like
11

It looks like this page: https://docs.looker.com/dashboards/using-markdown-in-text-tiles which lists what’s allowed in text tiles, is also the reference for .md files in projects.

The following Markdown syntax is not supported in dashboard text tiles:

Math
Images with alt text
Links with alt text
Language-specific syntax highlighting
Headers
Strikethrough using two tildes
Sublists
Indentation

also don’t seem to work in a .md file, which is a hint that it’s the same set of rules.

12

I felt lazy for just saying that. I found out what library we use to create our markdown, and while I’m not sure if that’s privileged info or not (if I find out it’s not, I can share), I discovered some secrets you may enjoy. Here’s a particularly salient one!

While markdown floating doesn’t seem to work very well, try HTML.

<div style="float: right">
stick to the right!
</div>
13

This was what I had tried and mentioned above, in the css style tag and float didn’t work for me on a md document page, just comes up in the middle of the page!

1 Like
14

Oh, weird! I wasn’t sure what syntax you’d tried.

Mine looks like this, with that syntax:

image.png
image.png2230×1294 84.1 KB

I guess it is kind of the middle of the page. There must be a margin of some kind… Is that what you’re referring to?

15

I tried float left (want navigation on the left). Seems float left and not trying to do anything with it results in the same alignment…middle of the page.

1 Like
16

Oh I get it— You want it where my x-marks-the-spot is?:

37%20AM.png
37%20AM.png2238×1076 88.4 KB

I think this must be the same sort of default margin that’s present on dashboard text tiles, which as far as I know is enforced by the pre-packaged Looker CSS and can’t be changed.

17

sad times, sticking navigation in the middle of the page looks bizarre, the built in md navigation this post is about is perfect apart from it has to be in the same project.

1 Like
18

Yeah, that would be the easiest way for sure. I’ve asked if it’d be possible to add that capability.

19

FR: https://github.com/looker/analytics/issues/9183

20

A post was split to a new topic: Markdown navigation not compatible with IDE folders