Add contributing options on every page

[jseldess]

• Edit This Page, which should prompt user to fork the repo
• Report Doc Issue, which should open an issue with template text
  and community label
• Suggest New Content, which should open an issue with template text
  and community label

To NOT add contributing options to a page, contribute: false must be set in the page's front-matter.

---

This change is 

[beneschbot]

It works!

[benesch]

The code all looks good to me (modulo those two comments), but of course we'll need @kuanluo to weigh in on the design!

[benesch]

I think you can kill the empty &label=?

[jseldess]

Good catch. Done.

[benesch]

To be valid HTML, these &s (here and the line above) should be escaped as &, though most browsers don't really care.

[jseldess]

Thanks, @benesch. I think I caught them all now.

[jseldess]

TFTR, @benesch!

@sploiselle, @mjibson, @spencerkimball, @petermattis, @bdarnell, if you have additional thoughts/feedback, please share.

@kuanluo, can you chime in on styling? I've tried to use some other "button" conventions here, while trying to keep these options a bit less in-your-face than a real button. But the drop-down coloring should still be styled. Interested in your overall design guidance, but some specific questions:

• Is the placement good?
• What should happen when the page title is long? Should the page title wrap early due to the contributing options (currently what happens)? Or should the contributing options be repositioned below the title?
• How should these contributing options behave on smaller screens? It's not likely that someone will "Edit This Page" on a phone, but they may want to report and issue or suggest a new topic...

[jseldess]

For clarity, this is what it looks like:

[bdarnell]

LGTM

[kuanluo]

Great idea, @jseldess! Some ideas to your questions:

Is the placement good?

I like the current placement, and we can certainly track the usage and improve from there. One idea is to repeat the button at the end of the page, next to "Was this page helpful" to capture those who read the whole way through and might have ideas/suggestions.

What should happen when the page title is long? Should the page title wrap early due to the contributing options (currently what happens)? Or should the contributing options be repositioned below the title?

I prefer having the contribution options be repositioned below the title. My hypothesis is that the second option would require less work and be equally effective.

How should these contributing options behave on smaller screens? It's not likely that someone will "Edit This Page" on a phone, but they may want to report and issue or suggest a new topic...

If we position the contributing option below the title, per the question above, then on mobile, it should behave the same as on desktop. Currently, it looks like the dropdown is slightly cut off on the right edge in the smaller window, but other than that, it works just fine. Another suggestion would be to place "edit this page" as the last option in the dropdown, so report and suggest are prioritized?

On the design of the dropdown itself, I overall love it. Just a few nits to make sure we don't have different type spaces floating around on the site. :)

1. The title contribute seems to have a heavier type weight than the site navigations above. Can you make sure the all caps stylings are the consistent?
2. Would be great to have the dropdown options follow the same type/line-height as the docs nav on the left. The current treatment looks a bit light and tight. The hover would be a text color change to green.
3. For the dropdown container, we don't use borders (unless it's a screenshot) and the drop shadow is a bit softer. Check out the "Run on any cloud or on-premise" module for the implementation details.

Let me know if you have any questions!

[jseldess]

@kuanluo, thanks for the feedback. I still need to deal with positioning, but please take another look at the styling of the menu. I've tried to address 2 & 3 above.

As for 1, I can't find relevant differences to the topnav. Weight and all caps seems correct. But please let me know if I'm missing something.

[jseldess]

@kuanluo, figured out how to make CONTRIBUTE match the topnav styling. Still need to work on positioning on smaller screens though.

[kuanluo]

LGTM, @jseldess! Thank you for taking the time to fix the styling. Much appreciated!

[sploiselle]

So cool, @jseldess! LGTM. Have one really minor nit.

---

Review status: 0 of 6 files reviewed at latest revision, 3 unresolved discussions.

---

_layouts/page.html, line 14 at r1 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

Thanks, @benesch. I think I caught them all now.

Same thing here with the line feed

---

_layouts/page.html, line 14 at r3 (raw file):

      <ul class="dropdown-menu" aria-labelledby="dropdownMenu1">
         <li><a href="https://github.com/cockroachdb/docs/edit/gh-pages{{ page.url | replace: '.html', '.md'}}" target="blank">Edit This Page</a></li>
         <li><a href="https://github.com/cockroachdb/docs/issues/new?title={{page.title}}%20Doc%20Update%20&amp;body=Re%3A%20%5B{{page.title}}%5D(https%3A%2F%2Fcockroachlabs.com/docs/{{page.url}})%0A%0APriority%20(Low‚%20Medium‚%20High)%3A%0A%0A%23%23%20Issue%20Description%3A%0A%0A%23%23%20Suggested%20Resolution%20&amp;labels=community" target="blank">Report Doc Issue</a></li>

I'd add a line feed (%0A) to the last item so there's a pre-populated space users can begin typing.

<li><a href="https://github.com/cockroachdb/docs/issues/new?title={{page.title}}%20Doc%20Update%20&amp;body=Re%3A%20%5B{{page.title}}%5D(https%3A%2F%2Fcockroachlabs.com/docs/{{page.url}})%0A%0APriority%20(Low‚%20Medium‚%20High)%3A%0A%0A%23%23%20Issue%20Description%3A%0A%0A%23%23%20Suggested%20Resolution%20%0A&amp;labels=community" target="blank">Report Doc Issue</a></li>

---

Comments from Reviewable

[jseldess]

_layouts/page.html, line 14 at r3 (raw file):

Previously, sploiselle (Sean Loiselle) wrote…

I'd add a line feed (%0A) to the last item so there's a pre-populated space users can begin typing.

<li><a href="https://github.com/cockroachdb/docs/issues/new?title={{page.title}}%20Doc%20Update%20&amp;body=Re%3A%20%5B{{page.title}}%5D(https%3A%2F%2Fcockroachlabs.com/docs/{{page.url}})%0A%0APriority%20(Low‚%20Medium‚%20High)%3A%0A%0A%23%23%20Issue%20Description%3A%0A%0A%23%23%20Suggested%20Resolution%20%0A&amp;labels=community" target="blank">Report Doc Issue</a></li>

Done. Thanks, Sean.

---

Comments from Reviewable

[jseldess]

_layouts/page.html, line 14 at r1 (raw file):

Previously, sploiselle (Sean Loiselle) wrote…

Same thing here with the line feed

Done.

---

Comments from Reviewable

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/4b2d680607a2f7146a713bb26ddb9c0fff8e0aaf/

[benesch]

How's this, @jseldess?

I force-pushed your branch, so you'll want to git fetch origin && git checkout contribute-link && git reset --hard origin/contribute-link to get my changes locally, should you need them. Fair warning: that command will blow away any local changes you have on that branch.

[jseldess]

Perfect, @benesch! Thanks very much.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ee58a638f691b219216a3c04117fe6a1822f0f37/

[benesch]

My pleasure, @jseldess!

[sploiselle]

@benesch There's nothing you can't do! Can I get a tl;dr of what you did to the <h1> and the Contribute button?

[benesch]

Yeah, totally! Are you familiar with flexbox? It's a new layout model for CSS that makes it possible or at least a whole lot less painful to achieve certain layouts. This contributing button is a good example of where flexbox shines; without flexbox, I think you'd need JavaScript.

Basically, you opt-in to flexbox on a per-element basis by specifying display: flex. I did this for the parent container, .post-header, of the page title and contribute button. By default, flexbox won't let elements wrap, so I opted in with flex-wrap: wrap. Then, the justify-content: space-between asks that any extra space on the line be placed between the child elements. So when the page title and contributing button are on the same line, the extra space is put between them, pushing the contributing button all the way to the right. When the contribute button is wrapped to the next line, there's only one element per line, so they both appear at the start of their lines.

[benesch]

Oh, I forgot to mention: all that margin hacking (-30px on the container, 30px on the children) ensures that the title and the contribute button always have 30px of space from each other, but no space from the edge of the container. Adding a margin-left: 30px on the contribute button doesn't quite work, because it'll be indented 30px when it wraps. Adding a margin-right: 30px on the page title also doesn't work, because it means it can't use the last 30px of the line to display a word it otherwise could fit.