-
Notifications
You must be signed in to change notification settings - Fork 880
Docs: Update to reference-style markdown links #3321
Conversation
|
Can one of the admins verify this patch? |
|
Paging @joshix et al. for a review here.
We typically welcome any kind of fixes, including bulk documentation changes if they make sense and improve uniformity! For this specific PR, I'm deferring to our docops friends for the final word.
We don't have such a policy. On the opposite side, some of our docs may be in need of a bit of love, so contributions are much appreciated. |
|
Sounds good! I forgot to mention that this patch fixes some links that used the full github URL to the markdown doc, which would "break" the coreos.com documentation library links (i.e., instead of linking to the generated HTML file, it would link back to the github doc). I'll wait for @joshix to weigh in on this and go from there. |
|
@Crosse Thanks for this! We'll get someone on reviewing it. Could you rebase this to resolve the conflict in Documentation/hacking? Documentation fixes are welcome and a good way to get on the ground running as a contributor, since you can learn a bit about the software even while applying style fixes and the like. |
|
Okay, I've rebased my branch and fixed an inline-style link that was introduced to hacking.md in that last commit. (As an aside: after I rebase and fix stuff, I'm doing a "git push -f" to update my remote branch. Is that what I should be doing? I'm a little shaky how to work with PRs.) |
|
@Crosse Thank you for rebasing. Yes, you appear to be doing it correctly. We like commits squashed into reasonable units, with a rebase push to your fork and branch, as you've done here. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Crosse This looks really good! I'm glad you've taken an interest in enforcing the style guide.
I've got just a few small pieces of feedback here. Once you address those (and rebase again 😞 ) this will get my approval. Good job and thank you!
| [docker2aci]: https://github.com/appc/docker2aci | ||
| [goaci]: https://github.com/appc/goaci | ||
| [k8s-pods]: http://kubernetes.io/docs/user-guide/pods/ | ||
| [running-docker-images]: running-docker-images.md |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Broken link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tested these links again and they all worked for me... is it the running-docker-images link that's broken?
| @@ -22,3 +22,5 @@ Since rkt v1.2.0, rkt gives access to systemd-journald's sockets in the /run/sys | |||
| #### /dev/log | |||
|
|
|||
| Since rkt v1.2.0, if /dev/log does not exist in the image, it will be created as a symlink to /run/systemd/journal/dev-log. | |||
| [networking-dns]: networking/dns.md | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Broken link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tested this link again and it worked for me. I'm not sure what is going on here.
| [dns]: dns.md | ||
| [examples-bridge]: examples-bridge.md | ||
| [ipvlan]: https://www.kernel.org/doc/Documentation/networking/ipvlan.txt | ||
| [ipvlan-dupv6]: http://thread.gmane.org/gmane.linux.network/363346/focus=363345 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This link is also broken. Might want to get rid of it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wasn't sure what to do with this. Gmane says they're still bringing all their old content online, but gmane.linux.network isn't there yet and I wasn't able to find another source for this message. I'll just remove the link entirely, I think.
As per https://github.com/coreos/docs/blob/master/STYLE.md, reference-style links should be used in documentation. This converts all documentation to use this format instead of inline links. Inline links that refer to anchors in the same file were left unchanged.
|
@ElijahCaine I checked the links you said were broken, but they all worked for me, so I'm not sure what's going on there. I rebased and removed the dead Gmane link in networking/overview.md. Could you verify whether those other links are still broken for you? |
|
Thanks, folks! |
As per https://github.com/coreos/docs/blob/master/STYLE.md,
reference-style links should be used in documentation. This converts all
documentation to use this format instead of inline links.
Inline links that refer to anchors in the same file were left unchanged.
This is part one of a larger task where I'd like to work on updating the documentation to abide by the CoreOS style guide, as well as generally clean up the docs grammar- and content-wise, etc. If you're not interested in this type of bulk documentation fix, let me know! I know some projects would rather not update docs unless the content itself needs to change.