I'm moving an open source project's documentation over to Github Pages but I'm stuck on moving the .rst files.
We have a ReadMe.rst which you can see here in the code. I'd like to link to that page from our main documentation page but GitHub doesn't render the .rst as HTML so the browser simply downloads the text of the .rst file when you click the link).
There are of course tools to render .rst as HTML but that's a serious extra step. The whole reason we started using .rst was entirely because GitHub renders it automatically in code pages. You'd think there'd be some way to get this authomatic rendering happening for Github Pages...
GitHub Pages does not have support for .rst/RestructuredText. It only supports Markdown and Textile conversion to HTML.
GitHub Pages does not have support for reStructuredText directly, but Anne Gentle has created a nice demo of how you can get something working with reasonably simple steps:
https://github.com/annegentle/create-demo
Especially useful to look at the github workflow for how to automatically generate the needed HTML from reStructuredText sources on every commit.
Related
I want to update Topic/page titles on my GitHub wiki (which is currently using Markdown syntax). When I do that using the GUI it renames the Markdown files, and breaks all of the links.
I know that I can rename the Topic files in the Git repository and push the changes, but that doesn't help the broken links.
Is there a way to avoid this, and make GitHub Wiki's behave more like other Wiki products? I could not find an better way on GitHub documentation.
Welcome to StackOverflow. As best I can determine you cannot rename a GitHub Wiki page without its markdown file also being updated to the new name. The two are tightly coupled.
This Web Applications (StackExchange) Question has some alternatives you may consider, i.e. instead of renaming the page, create a copy. Then edit the original page so that it directs visitors to the new page via a link. This way the original page link remains valid but directs visitors to the new page.
I am creating a blog using github pages and jekyll. I wonder if there is a way to embed code snippets from a github file (i.e., a file in a repo) in a blog post. I can find a solution on this page about embedding gists: https://gist.github.com/benbalter/5555251.
No direct solution for github files, though.
Jekyll has a pretty nifty syntax-highlighting system (provides _sass/sytax-highlighting.scss is present and correct), so it would be possible to just copy the code over into a blogpost, using `s to wrap the code.
As per actually embedding from a Github repo, there is a pretty nifty project here, if you want to check it out.
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)
I've used GitHub pages to generate a beautiful website for my project (this one). Now I want to keep the documentation of my project up to date, and having everything in a single README.md file is probably not scalable to the many features we are adding.
So, I thought that the best place to keep the documentation is the GitHub wiki, but I'd like to integrate the wiki to the gh-pages generated site, keeping the beautiful layout.
How would I take the GitHub wiki and generate an HTML web site with a customizable layout?
Here is an example URL for a wiki:
https://github.com/golang/go/wiki
On the same page you will find a clone link:
https://github.com/golang/go.wiki.git
Then run the Markdown files through Hugo or even create a new repository
to the host site based on the Wiki.
You could include your wiki as subtree.
BTW, GitHub Pages now no longer need the gh-pages branch. Create a repository named your-user-name.github.io; it will automatic generate to a website. See GitHub Pages for more detail.
How do I create a ToC or a sidebar menu in a GitHub Wiki?
I saw some mentions of it and gollum the backend seems to support it, but how do I do it in a current GitHub project?
It should best be based on the headers I have in the page automatically.
These links all mention it, but do not show how to do it:
https://gist.github.com/379469 - some JavaScript hack
https://github.com/blog/774-git-powered-wikis-improved - GitHub mentioning it:
"GitHub Wikis have a little-documented ability for footers and sidebars, something which some of
our git-based Wiki authors are familiar with. The new Wiki editor gives you limited web-based
editing of the footers and sidebars you have on your site. "
While your solution works, there's an easier way to do it using GitHub's web interface. You can simply create a page named _Sidebar and/or _Footer.
See detailed instructions in Github Wiki sidebar menu builder with multi-level.
Edit The original article is gone and I can't find it in the cache so I've updated the link.
When you are in the wiki of your project, there is a link Add a custom sidebar. Click that.
Now you have a page that you edit as you would edit any other Markdown page. To make a table of contents you have to do it manually though. There is no automated method (as of August 2014). So for example:
# My menu
* [Home][home]
* [Technical documentation][techdocs]
* [User manual][usermanual]
[home]: https://github.com/myproject/wiki/Home
[techdocs]: https://github.com/myproject/wiki/Technical-documentation
[usermanual]: https://github.com/myproject/wiki/User-manual
Okay. Let me see if I understand this correctly:
Clone your GitHub wiki. (There’s a Git section in the wiki. You can checkout your wiki-like code.)
Create _Sidebar.md
In normal wiki pages, use [[link]] for the sidebar
Commit and push back to GitHub
This process is a pain in the ass. I’m surprised this “gollum” wiki has any acceptance.
Also: _Sidebar.md is therefore global for all pages. I would have to organize my wiki into folders, so I can define different sidebars for different pages.
Note that the original question was about creating a side bar (easy, solved in the answers) or an actual table of contents (not answered).
One thing I can say is that the gollum 2.1 wiki syntax allows for a [[_TOC_]] tag, but a GitHub wiki won't recognise that (yet?).
I think this is described in the Gollum README. (See the header and sidebar sections.)
Essentially, you make a _footer.ext and _sidebar.ext in the directory containing the page content.
I have implemented the npm module github-wiki-sidebar to help github users to easily create and maintain the sidebar menu.
Source and Result:
https://raw.githubusercontent.com/wiki/adriantanasa/github-wiki-sidebar/images/github-wiki-sidebar-generator.png
Source pages (as displayed in Wiki admin):
Home
Installation
Roadmap
Usage
Usage: Command line modifiers
Usage: Init Mode
Result (with customised order):
Home
Installation
Usage
Init mode
Command line modifiers
Roadmap
Pre-requirements:
clone your github wiki repository locally (displayed on the bottom-right of the Wiki UI)
install the github-wiki-sidebar
git clone <https://github.com/<username>/<my-project-name>.wiki.git
npm install -g github-wiki-sidebar
Create/update your wiki menu:
create new pages / rename pages on your github.com wiki admin
execute locally the github-wiki-sidebar script in your wiki repository folder
cd /path/to/<my-project-name>.wiki
# this fetches latest changes, generates sidebar file (_Sidebar.md) and pushes changes to github
github-wiki-sidebar --git-push
The module allows customisation of the markdown output including ordering of items, the category separator, the template for the menu, the format of links and others.
GitHub will auto-generate a document table of contents:
Make the doc type AsciiDoc instead of Markdown.
Insert :toc: at the start of the document.