Add anchors to bullets

[todb-r7]

Every bullet is anchored with a short <a name> tag and includes a superscript link anchor at the end. This makes life easier for me when I want to refer people to a particular guideline, such as:

https://github.com/rapid7/ruby-style-guide/blob/add-anchors/README.md#no-and-or-or

When dealing with new Rubyists and their contributions to my project, I want to drop them exactly on what rule I'm talking about when they don't know about the Ruby Style Guide, instead of telling them to scroll around or ctrl-F or anything like that.

This PR implements many of the suggestions in #319.

[todb-r7]

These margins will want to be reset eventually. First attempt at auto-resetting with VIM gqG was kind of a disaster.

[Ajedi32]

This pull request adds anchors, but doesn't seem to include any user-friendly way of discovering them.

See also #319

[bbatsov]

Yeah, as I already mentioned in #319 I think that the superscript [link] at the end of each rule is the way to go.

[bruno-]

When this is updated and merged this guide will ✨

[todb-r7]

Thanks for the pointer! I was experimenting with some linking tactics -- my only light concern with linking at the end was that you'd end up on the last of a multiline bullet. But, I can't figure any other way while retaining any kind of sane formatting.

[Ajedi32]

@todb-r7 Check out the second approach I suggested in #319:

This style is also very unobtrusive and clear in the rendered markdown, and the anchor points to the beginning of the line. The plain-text is a bit uglier though.

• Use Unix-style line endings. (*BSD/Solaris/Linux/OS X users are covered by default, Windows users have to be extra careful.) ^{[[link](#unix-line-endings)]}

Source at start of bullet:

<div name="unix-line-endings"></div>

Source at end of bullet:

<sup>[[link](#unix-line-endings)]</sup>

Basically, I suggested putting the anchor itself at the start of the bullet while still putting the link at the end.

[todb-r7]

I'm implementing the end of line anchors now.

[todb-r7]

@bbatsov what do you think?

[todb-r7]

Incidentally, I profess my love for your work on our company blog. Thanks!

[todb-r7]

Updated the description to reflect the current state of the PR.

[bbatsov]

Looks good to me. Squash all the commits into one and we'll be good to go.

[bruno-]

I just checked @todb-r7's branch and I found:

• the first anchor in this section jumps to an unexpected paragraph
• this paragraph and the one below it have the same link percent-q

Btw fantastic job 👍

[todb-r7]

I'll fix the problems described by @bruno- but just out of curiosity, would you like me to squash commits and force push, or open another branch? I can do either (personally I don't care about lots of small changes and backtracks, but I'm not a heavy git bisect user.)

[bbatsov]

Squash and force push.

[todb-r7]

Man I can't just force push i always do this delete and re-push dance so I'm sure. I can't do it!

[todb-r7]

But commit 4bd7012 is up, as well as the original set of commits, now at https://github.com/rapid7/ruby-style-guide/tree/nonsquashed-add-anchors (for future readability until I toss that branch).

[bbatsov]

No need to preserved the complete commit history. For most people it'd be best of the commit message was simple [Fix #319] Add anchors to rule bullets (or something similar).

[todb-r7]

Ah gotcha.

[todb-r7]

Rewriting history always creeps me out, I'm always afraid I'm going to sleep with my grandmother.

[bbatsov]

👍 Great work! (if you're into Rails feel free to update the companion guide as well :-) )

Rewriting history always creeps me out, I'm always afraid I'm going to sleep with my grandmother.

I'm sensing a Futurama reference here. :-)

[bruno-]

So much win here guys 👍

[todb-r7]

Yeah sure. It looks to be about the same length. Thanks!

[Ajedi32]

👍 Awesome!