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.
Related
Have read about differences of the two here: https://learn.microsoft.com/en-us/azure/devops/project/wiki/provisioned-vs-published-wiki?view=azure-devops.
Would like to try out code as wiki, however, want to have a backup plan in case I want to switch back to the provisioned one.
Once I have tried the "published code as wiki" does anyone know how to import the contents from a repo backup and make it "provisioned one"?
If you have already created a project wiki and add a code wiki, the two wiki's will coexist (see screenshot):
If the Code wiki is not the way to go, you can unpublish it only leaving the project wiki in place.
If the Code wiki is the way to go, removing a provisioned (project) wiki doesn't seem to be an option in the UI. Still, there are options to Delete default project Wiki in Azure DevOps using the API.
As another solution said, you can unpublish the Code wiki if you want to keep the project wiki.
If you want to keep only the Code wiki then you can download the project wiki as a git repo and replace all content. After having pushed the new content you can delete the (old) Code wiki.
Editing history will be lost but that is hopefully not important to you.
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 would like to create a "Revision page" where the people can see on what I've been working using GitHub there's an example about what I mean:
It is supposed to show the commits from my GitHub repository.
A) More information is required
Firstly, could you clarify if it is your intention to
Show the Commit history for a single repository, or
You wish to show your commit activity across multiple repositories
Also:
You wish to have this information displayed on Github, or
You
wish to have this information displayed on an external site.
B) Displaying information on GitHub
If the intention is a combination of 1 and 3, then my first suggestion would be to check the existing functionality of GitHub, which has such a feature built-in.
This can be accessed by navigating to your repository, and simply clicking the Commits button. An example of the results can be found here:
Example GitHub Commit History
C) Displaying information on an external site
As you mention that you have limited experience with PHP, I would certainly start by evaluating GitList:
GitList allows you to browse repositories using your favorite browser,
viewing files under different revisions, commit history and diffs.
GitList is free and open source software, written in PHP, on top of
Silex and the Twig template engine.
If you feel confident that you could create your own solution to display the information in an external web page, then you should begin by familiarising yourself with the GitHub Developer Documentation, and specifically:
List commits on a repository
It is also worth examining the following article and existing GitHub project in order to enhance your knowledge:
How to Use Github’s API with PHP (SitePòint Article with code)
GitHub PHP Client (GitHub Project)
It may be that you can clone one of these projects, strip it down to the features essential for your needs, and customise the UI.
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.
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.