How to create documentation linked with GitHub? - github

I was just reading this elasticsearch link. I found edit option with every heading which was redirecting me to GitHub website. I know git provides wiki option with every account but that is hosted on GitHub only and supports limited features.
How can I make documentation like this that is linked to GitHub?

It looks like they're using AsciiDoc and just put the repository on Github.
The edit links don't appear to be a special feature of AsciiDoc. They're simple URLs of the form https://github.com/<owner>/<repo>/edit/5.x/<path>. Presumably someone regenerates the site after they accept a pull request.
This will work with most site generation tools, it doesn't appear to be anything specific to AsciiDoc.

I read:
https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/nest-getting-started.html
Then I want edit, it redirect to:
https://github.com/elastic/elasticsearch-net/edit/5.x/docs/client-concepts/high-level/getting-started.asciidoc
Link source code:
https://github.com/elastic/elasticsearch-net/blob/5.x/docs/client-concepts/high-level/getting-started.asciidoc
URL file:
elasticsearch-net/docs/client-concepts/high-level/getting-started.asciidoc
The different is URL parameter: edit and blob. How to create documentation linked with GitHub? So simple, use this convention when create static document file.

Related

How to have multiple markdowns in the same gist

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?

Github html preview from html file not working

I Have seen several posts regarding this feature to preview HTML file on GitHub. Some suggest prepending https://htmlpreview.github.io/ before the real URL and some suggestions to create GitHub pages that I don't want to do now because then I have to re-create most of the thing on .yml
But my confusion is why this link showing HTML preview but not mine when I prepend the same string on my repo's HTML page. Please let me know If any other way I can see the HTML preview on github
Working:
https://htmlpreview.github.io/?https://github.com/bartaz/impress.js/blob/master/index.html
Not Working:
https://htmlpreview.github.io/?https://github.com/sany2k8/setuptools/blob/master/How_to_Install_Spark_on_Ubuntu.html
Showing 404 Not Found
Error: Cannot load
https://raw.githubusercontent.com/sany2k8/setuptools/master/How_to_Create_Github_Pages.html:
404 Not Found
Check these steps:
-Your repository is public.
(Settings>General>Danger Zone>Change repository visibility>Make public)
-The size of the files are not very large.
-The Repository link is in HTTPS and not in SSH.
EDIT:
I found this question about the private repository and preview, if you want to take a look.
When your html file is excessively big then often github may fail to open the file. In such cases you can check the raw version of the HTML file.

Is it possible to have 2 urls for a single Github repository

I was wondering if it's possible to have 2 Github urls that point to the same repository. The reason I want this is I posted a link to a repository somewhere where it is not possible to change my submission. Now I want to put the repository on my resume, but the repository name is so long that it won't fit on one line. I'd like to have a way to put it on my resume without breaking the original link.
The short answer is no: the GitHub URL is unique.
Your options are:
Work with the GitHub URL as-is (span multiple lines).
If your résumé supports HTML, use an href.
Fork the repository to your account, rename it with a shorter title, and put that in your résumé. Interested readers can click through the "forked from" link.

Generate github pages with navigation elements

I have a project on github that includes a number of markdown files (introduction, user guide, examples, reference).
I want to create a website using Github Pages based on these files that also includes a navigation element of some sorts, like a simple sidebar containing links to all the generated pages.
It seems that, out-of-the-box, pages generated with Github Pages are all stand-alone with no way to navigate between them.
Is there an easy way to achieve this, or is this use case too complicated for github pages? The documentation seems to be lacking on this point.
The Markdown to link to pages within the same folder
[__PageA__](PageA.md)
[__PageB__](PageB.md)
To link to pages in other folders just put in the relative link like this
[__PageC__](FolderC/PageC.md)
[__PageX__](../../PageX.md)
This works for files hosted on GitHub ... how you then use these to generate a standalone website you would need a tool that converts Markdown to HTML, something I have not looked into.

Embedding a dynamic file using the "view file" macro

The view file macro allows embedding documents (.ppt, .pdf, etc) on a Confluence wiki page. Limitation is, documents must be on attachments.
So question, is there a way to load dynamically a file located into an SCM's deposit?
P.S. Current SCM: Perforce.
UPDATE: As I see, there is no official Perforce plugin.
You may of course include a link to that file, if Perforce provides a way to link items. We use that a lot, to include content that is stored in Subversion, and document the standing, the usage, ... in Confluence then. The user has to click on that link to get that file, but I think it is necessary anyway, because your authorization rules are not known to Confluence.