| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677 |
- = Github Tips
- :author: mitm
- :revnumber:
- :revdate: 2019-09-08T23:24:11.262Z
- :experimental:
- ifdef::env-github,env-browser[:outfilesuffix: .adoc]
- == Inserting code links into forum posts
- There will come a time when you may wish to insert links from github into your forum posts to highlight problems in code, clarify some point your making, or provide more background. Whatever the reasons, here are a few pointers that will help make your posts more robust.
- == Creating permanent links
- To create a link to a specific line in a file located on github all you need to do is click the line number inside the file. A three dot tag will appear and the line will be highlighted in yellow.
- image::wiki/github_tag.png[github_tag.png,align="left"]
- This will append the line number to the URL in your address bar with the format `#L<number>`, in our case `#L61`.
- ```
- https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/plugins/java/com/jme3/material/plugins/J3MLoader.java#L61
- ```
- Click the three dot tag and a option menu will appear.
- image::wiki/github_tag_menue.png[github_tag_menue.png,align="left"]
- Select the `Copy permalink` option and now you can paste the URL into any forum post or wiki issue and the code display window will show your selection like so:
- .jMonkey forum
- image:wiki/github_jme_forum.png[github_jme_forum.png,align="left"]
- The same thing applies to github.
- .Github issue
- image:wiki/github_issue_write.png[github_issue_write.png,align="left"]
- image::wiki/github_issue_preview.png[github_issue_preview.png,align="left"]
- If you want to select more than one line:
- . Select the start line number.
- . Hold down the kbd:[Shift] key.
- . Select the ending line number.
- image::wiki/github_multiline.png[github_multiline.png,align="left"]
- All the lines between will be highlighted as well. This will change the URL using the format `#L<number>-L<number>`, in our case `#L83-L86`.
- ```
- https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/plugins/java/com/jme3/material/plugins/J3MLoader.java#L83-L86
- ```
- The above mentioned links are just normal URLs. This means that this line will be linked forever at this point in this file as long as it exists. What if the line changes or what you were referring to goes away or moves to another line? Canonical URLs to the rescue!
- == Canonical URLs
- A Canonical URL will attach the SHA hash number of the commit to the URL so even if the file changes, that link will always point to the same file and same line.
- .Normal URL
- ```
- https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/plugins/java/com/jme3/material/plugins/J3MLoader.java#L83-L86
- ```
- .Canonical URL
- ```
- https://github.com/jMonkeyEngine/jmonkeyengine/blob/a9afcecc41b54feaac253e38d2f2282c8c6027fc/jme3-core/src/plugins/java/com/jme3/material/plugins/J3MLoader.java#L83-L86
- ```
- Notice the hash commit number is now part of the URL.
- To make the Canonical URL just select the kbd:[y] hot key after selecting the line number or numbers. Once you have done this, all links from thereafter will be Canonical URLs.
- '''
- Suggested reading:
- * link:https://help.github.com/en/articles/keyboard-shortcuts#source-code-editing[Source code browsing]
- * link:https://help.github.com/en/articles/getting-permanent-links-to-files[Getting permanent links to files]
|
