Github helpfully renders Markdown (.md) files to HTML when viewing on github.com (for example, this README.md).
When viewing any other source file, it is shown as unrendered source code (for example, this .gitignore). A handy feature this gives is linking directly to a line in the source by clicking the line number (for example, like this).
How can I view the unrendered source of Markdown files on Github (so I can link to a particular line in the source)?
note: I know of the "Raw" button, however it does not provide any of the nice UI Github has.
If you don't want to use the "raw" button, you can (since June 2021) add ?plain=1 to your GitHub markdown file URL:
Appending ?plain=1 to the url for any Markdown file will now display the file without rendering.
As with other code files, it will also show line numbers, and can be used to link other users to a specific line or lines.
For example, appending ?plain=1#L52 will highlight line 52 of a plain text Markdown file.
Example:
https://github.com/git/git/blob/master/README.md?plain=1#L49-L51
Since Sept. 2021, there is a button which adds the ?plain=1 for you:
Use the "Raw" button. For instance, if you were looking at README.md there is a Raw button in the Navigation. This can be simple URL change (from blob to raw), but in this case becomes a separate link.
Edit: There is no "pretty" view for the Markdown source. There's the converted HTML view, the Raw view without the UI, and the Blame view. Only the Blame view provides you with the ability to link to a specific line within the source.
Edit 2: The other option is to use Anchors within the README.md. If you take the Installation title for example, you can directly link within the content of the Markdown file. Assuming you don't have anything hidden within the Markdown itself, this is closer still to solving your original question.
Using the "Blame" button, you are able to see the source of the Markdown (for example, like this).
Unfortunately, "Blame" comes with extra UI elements which make the source more cluttered.
Refined Github provides an additional "Raw" button to view the raw source and link to a specific line:
I ran into this issue, as a complete surprise to me, on a file with a .wiki extension. It appears that files with .wiki, .mediawiki, and .wikitext extensions are recognized and rendered as HTML, with a table of contents even. I guess it makes sense, what with GitHub projects having wikis and all.
That's nifty, but this one particular case, I really wanted the raw wikitext to be visible and copy-pasteable, not some rendered representation of it.
The only half-way solution I found was to use a bogus file extension that isn't one of the ones recognized by GitHub, and then a .gitattributes to tell GitHub how to syntax highlight it, e.g.:
*.wiki_ linguist-language=mediawiki
I'm not thrilled about this, but all the good extensions were already "taken" according to the languages.yml linked above.
Related
I do apologize if similar question already put, but I haven't found one.
I would like to change the default project description file name (called README.md) to be a custom name (let's say XXX.md) and I wonder if it is possible to be the XXX.md the initial readme file for the project (typical situation: you open the project Code page and you will see the content of XXX.md down at bottom).
I would like to verify if this approach possible in general, but I am mainly interested in Github and Bitbucket services. I briefly checked project settings and I cannot find there such customization. Is it even possible?
GitHub, at least, doesn't provide the ability to do this. It is possible to use a different format (e.g., README.asciidoc or README.rst), but the root file must be called README.
Note that you can include other text markup documents like this and they'll be rendered if they're visited, it's just that they won't appear at the bottom of the file listing like a README will.
I would like to create a gist in which I can present a main markdown document containing a set of links. These links will point to secondary markdowns which actually contain the code examples and technical explanations:
Here's what I have so far. I have included two markdown files:
Notes.md: contains a listing of existing secondary markdown documents
tree_traversal.md: an example of such a secondary markdown
As you can see I have tried to add a link in Notes.md to tree_traversal.md using the following syntax:
example of a [link](tree_traversal.md)
However there are two issues:
The Gist server attempts to display both Notes.md and tree_traversal.md. This is not what I want. I want to have Notes.md display first, then click on the link to navigate to tree_traversal.md
When I actually click on the link I created in Notes.md I get a 404 Page not found error.
Is it possible to have a multi-page gist like this? If so how? If not is gist only designed to have one markdown file?
Mousing over the tree_traversal.md header we see that it is a link to
https://gist.github.com/awa5114/4052ba8adb51779192a4a715a048f8ca#file-tree_traversal-md
Try simply linking to #file-tree_traversal-md in Notes.md. This should let you link between files, though they will both still be rendered in a single view.
Gists are designed for quick snippets, not documentation. Maybe you are looking for GitHub wikis? Wikis can be cloned via Git, managed locally, and pushed back, and they render pages one at a time.
Or possibly GitHub Pages, which can be used to host static websites?
I wrote an extension for vscode. After installation the extension folder contains documentation in a markdown file. I want to provide a command that loads this file into the preview pane so it displays rendered with images and hyperlinks etc.
You can do this sort of thing interactively:
and I have the full path to the markdown file, so now all I need is details of the command that implements this context menu item.
Web search does not produce complete or usable results.
After cloning the VS Code repo and trawling through the source I discovered the markdown.showPreview and associated commands.
To give credit where due, Lex Li reported the corresponding package.json entry in a comment while I was looking.
Without parameters this previews the content of the active editor, but as I said in a comment, it supports an optional Uri parameter and the code looks like this:
let pathToManual = path.join(context.extensionPath, "manual.md");
let uriManual: vscode.Uri = vscode.Uri.file(pathToManual);
vscode.commands.executeCommand('markdown.showPreview', uriManual);
For information on constructing workspace relative paths see the answer from Mark. The joinPath method he uses requires a base path as a Uri which is conveniently available for the workspace but not for the extension path.
If you need information on things like showing preview to one side then given the dearth of documentation I recommend cloning the repo and searching it for "markdown.showPreview", then exploring nearby code. If you fold the methods it gets easier to survey your options.
Try:
vscode.commands.executeCommand("markdown.showPreview", vscode.Uri.joinPath(vscode.workspace.workspaceFolders[0].uri,'test.md'));
Your fileName there at the end of course. And that assumed you are in the first or only root of a workspace. You might be able to simplify it using:
vscode.Uri.path(<path to file)
instead of the joinPath that I used.
I have a markdown file with a number of codes and descriptions within it which will be used like a wiki.
A developer will be given a link, and the link should take them to the specific code within the markdown file.
Example of file:
#IAmAPizza
This declares that you are a pizza
#CordialComrade
You've encountered a cordial comrade who will eat your pizza.
...
#ZestfulZebra
You can't keep up with him, just go with it.
[test code](#test-code)
I am a testing code
I've tried navigating to the file in the repo and then adding #test-code to the address, but it doesn't do anything. I assume that the markdown isn't being rendered on the page.
Is there a way to navigate to a specific # within a file in an Azure Devops Repo?
Is there a way to navigate to a specific # within a file in an Azure Devops Repo?
We could try to open the markdown file in the repo under the Contents view. Then select the specific #, like: #ZestfulZebra:
Just as Hugh pointed, there is an option copy link to this selection. We could get the link after click the hyperlink symbol, it should be:
https://dev.azure.com/<OrganizationName>/_git/<ProjectName>?path=%2FReadme.md&version=GBmaster&line=64&lineEnd=64&lineStartColumn=1&lineEndColumn=14&lineStyle=plain
And the link for the markdown file is:
https://dev.azure.com/<OrganizationName>/_git/<ProjectName>?path=%2FReadme.md&version=GBmaster
So, it use the syntax &line=64&lineEnd=64&lineStartColumn=1&lineEndColumn=14&lineStyle=plain to locate the anchor we selected.
Now, we can simply parse this syntax &line=64&lineEnd=64 is used to locate the line number we select the code. If we change it to &line=64&lineEnd=65, it will select the lines 64 and 65. And the &lineStartColumn=1&lineEndColumn=14 is used to locate the start and end positions of the selected string.
Now, we could use this syntax with the link of markdown file to navigate to a specific # within a file in an Azure Devops Repo.
For example, we could use the web address to navigate the anchors in the MD:
https://dev.azure.com/<OrganizationName>/_git/<ProjectName>?path=%2FReadme.md&version=GBmaster&line=64&lineEnd=64&lineStartColumn=1&lineEndColumn=14&lineStyle=plain
Do you mean adding anchor link in markdown file? If so, I tested this syntax: [test](codeLink) without # and it works well.
I first get the code link in a code file in the repo:
Then add this:[test](https://dev.azure.com/{org}/_git/{repo}?path=%2FStartup.cs&version=GBmaster&line=4&lineEnd=5&lineStartColumn=1&lineEndColumn=1&lineStyle=plain) to markdown file:
Click test in the wiki to successfully navigate to the code:
My badges aren't showing on github README.md file but they show here on stackoverflow. Here are the markdowns:
I also noticed that html tags (that used to work in README.md files) now show as plain text. What am I missing?
There are hexadecimal binary numbers (in place of spaces) in your README.md. That's why it can't be parsed and represented as a markdown file:
Tip: make your editor display spaces/tabulation and other invisible characters. That's what I see when I open your README.md:
Ride my way<0x00>app<0x00>
<0x00>
<0x00>
So nothing to do with the way you display the badges.
I've removed these non asci-characters and just created a pull request (notice how github defines this change as BIN and can't display a diff):
And it's now displayed as it should: