Some projects have a CHANGELOG.md file where each version links to the range of commits that were made for that version. For example, this one. It looks like these links are automatically generated somehow, because the markdown only contains [1.0.0] where the rendered document has a link to https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0.
How does that work? I've tried to do something like this on my own project, but the rendered document just said [1.0.0]; no link was generated.
Presumably it has something to do with the tags, which follow a similar pattern (v1.0.0), but when I tried to create similar tags in my project, it still didn't work.
I also could find no reference to this on the GitHub help, or anywhere else for that matter.
Is this indeed an (undocumented?) feature of GitHub? If yes, how does it work? If no, how do these projects do it?
Note, I'm not interested in automatically generating a changelog from commits like this project does. I'm just interested in the mechanics of these hyperlinks.
You need to look beneath the surface of the Markdown, it's a simple trick he done by using the file compare feature to compare tags.
If you look at the RAW file, you should notice at the bottom he added links to each version number that has a compare link assigned to it.
## [1.0.0] - 2017-06-20
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
With pretty mode, you would see the link to the compare page.
Related
I document my software using the README.org file, which is rendered nicely in the master branch in GitHub. Now, suppose I create a tag v1.0 and want to share a link to that tagged version with others. Unfortunately, when one follows that link, he does not find my README.org nicely rendered, but only the archived code. So, what is the correct way of documenting a tagged version at GitHub? (of course, I am looking to re-use my README.org).
Just a short question:
Is it possible to show the current branch name in e.g. README.md automatically with a placeholder or something like that using GitHub Flavored Markdown?
No, I'm not aware of anything like that within READMEs or any other markdown documents when browsing through the source of your project. And nothing turns up when searching their help page either.
However, GitHub Pages offers all sorts of info about the repo the document is associated with. Of course, GitHub Pages is a very different thing than a README file, so that may or may not be helpful to you.
In github, is it possible to show the diff of a single file between two commits?
One can readily diff two commits, and it is possible to link to the anchor for a specific file in those two commits, but all files are included in that view. For example, https://github.com/adamginsburg/APEX_CMZ_H2CO/compare/a94a962db51e0f4e73ec3ba4170a0ca8269548da...adamginsburg:master#diff-22
I would like a similar view, but without the other files.
(I know how to do this on the command line with git, but I want to share this link with collaborators, so the command line approach is not relevant for this question)
I think your question can be consider a duplicate of this one :
How can I generate a diff for a single file between two branches in github
Unfortunately, the accepted answer doens't answer your expected behavior.
I really tried to exclude the other files without success, and since there not seems to have other means to filter it out but html anchor pointer, I guess what you already have is what best available with Github to pin point the change you want to talk about with your peers.
I can recommend you to use Vscode with the Git History, I know is not the same as having in Github but it allows you to see the changes of the code according to an specific file or the entire project, comparing with the actual code, see all the changes of specific file through the commits, I work with this tool and this is helpful for me, hopefully it will be helpful for you.
Git History Example Usage
You can use the GitHub File Diff extension available for Chrome and Firefox.
Disclaimer: I made this extension.
On GitHub, is there a simple way to reference an issue (eg: #1234) from within a markdown file such that it is displayed as a hyperlink?
I don't want to write out the full form each time, as in:
[#1234](//github.com/user/project/issues/1234)
In commit messages, issue numbers are automatically hyperlinked. Can this happen in wiki documents too?
(This is not a duplicate of this question which is simply asking about markdown hyperlink syntax.)
It doesn't happen in wiki documents.
You can use a relative url but it isn't that much of a shortcut. It also depends on where you are in the project.
For example in the Readme.md in the master branch of the project:
[#1](../../issues/1)
On the github wikis:
[#1](../issues/1)
Anywhere:
[#1](/user/project/issues/1)
(h/t to VertigoRay for suggesting this)
Does the wiki that installs with a GitHub repo support directories? Our wiki is cluttered with pages, and we are looking for a way to organize them better.
We tried pulling the repo, creating local directories, and moving things around, but when committed back, the wiki didn't pick up the changes.
I was having the exact same issue and tried variants of what you tried. Nothing stuck. Asked GitHub support about it and received a reply that essentially said "No, but we'll let the developers know that people are interested in this feature."
So the short answer is "No", and the long answer is "No, but maybe in the future."
Actually, it looks like github added support for directories recently.
I was able to do the following:
Move an existing markdown file to a new directory.
Create a new markdown file in an existing directory (created in the former step).
Create a new markdown file in a new directory.
In all cases, the existing pages were still there and new pages were added.
The one constraint that remains is that your file names must be unique. If you have more than one file with the same name, only one of them will show up in the wiki (I'm not sure which.. ).
The GitHub wiki (aka Gollum) does use directories but not in the way you may expect.
The documentation on the Gollum wiki could use some work but this is what I have figured out mostly via testing.
All files appear in the root of the wiki no matter where they are placed in the repo.
_Header, _Footer and _Sidebar files are per-directory, but inherited if there is
none present in a child folder.
File links can be relative to the source file (keep your files with your content).
So, if you want directories for namespacing you are out of luck. Consider using the {namespace}-{page} scheme for namespacing.
It's not the an ideal solution but the workaround would be to create a custom sidebar where you create a table of contents with links to your pages. I find this to be better than folders anyway because it allows you to have a link to a single page under multiple hierarchies.
Actually, there is still a limitation. Yes, you can add 1 level (so, 1 subfolder). But that's it! I refactored my whole documentation layout, creating multiple levels of subfolders for organisation, but that was a no-go.
sigh
I must say: I'm appalled by this Gollum thing. I'm surprised Github even picked it up.
Well, that's a disappointing missing feature!
What I try to do is to actually have directories under a docs directory and in each one, a README.md file.
Not great...but works for documentation and organizes stuff.
If you want to go further, you can have a different branch only with these files.
Still no intention of adding this 9/2022.
https://github.com/orgs/community/discussions/23914