How can I replace the View page source hyperlink at the top of my docs pages with a Edit on GitHub link when building a Sphinx site using the sphinx_rtd_theme theme?
I'm manually building a readthedocs.io-like site using GitHub Pages, but the link in the top-right of all my doc's pages still says "View page source" instead of "Edit on GitHub."
The theme's documentation lists a few relevant options (display_github, vcs_pageview_mode, and github_url), but it provides no examples. I've tried setting them at the root of conf.py and in html_theme_options to no avail.
How can I tell the sphinx_rtd_theme theme to change the View page source link to an Edit on GitHub link on all my docs' pages?
Use should set the display_github, github_user, github_repo, and github_version variables inside the html_context dict in conf.py. For example:
html_context = {
'display_github': True,
'github_user': 'buskill',
'github_repo': 'buskill-app',
'github_version': 'master/docs/',
}
These variables are intended to be set directly in the .rst files rather than in html_theme_options or conf.py in general. To make this actually apply site-wide as if it were defined in every .rst file, just put it in html_context.
See also:
https://github.com/readthedocs/sphinx_rtd_theme/issues/529
https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/breadcrumbs.html
Related
I have created a github Wiki page Introduction.md and sidebar file _Sidebar.md in the same directory in a private repo. When I click on sidebar link I'm redirected to raw page, although the link shows appropriate url.
page Introduction.md has below content
# Introduction <a name="heading--1">
This is a web application.
And the _Sidebar.md has below content:
# Table of contents
**[1. Introduction](Introduction.md#heading--1)**
On hovering the link on sidebar it shows correct url as:
https://github.com/testorg/ecom/wiki/Introduction.md#heading--1
But on clicking the link it redirects to raw page and shows the raw content for Introduction.md above
https://raw.githubusercontent.com/wiki/testorg/ecom/Introduction.md?token=GHSAT0AAAAAATESTINGTOKENAZG2ZMAQ33POCYYHFSBQ#heading--1
Why this type of behavior, What I'm missing here?
Almost there, however, is one small issue in your URL. Instead of
**[1. Introduction](Introduction.md#heading--1)**
Remove .md from the URL.
**[1. Introduction](Introduction#heading--1)**
I have a Github repository with an associated Github page (say, github.com/user/mypage), and I would like to include the URL to the Github page (say, user.github.io/mypage) in the About section of the repository. When I go to "Edit repository details", the Github page already shows up in the "Website" field and cannot be changed (which is fine) but it is not displayed in the About section. I've tried this with multiple repositories with associated Github pages, and all show the same behavior. Am I overlooking something blatantly obvious, or is it just not possible to include the URL here?
I tried for a week to link my GitHub Page to my GitHub repository. I just figured out how to do it and then found this post. I thought I would go ahead and post my answer. Doing so might be helpful by making this question more visible in future internet search results.
Click on the gear icon in the upper-right of your GitHub repository to the right of the word "About" (shown in the red circle below):
Paste the URL of your GitHub Page into the Website bar in the window that pops up. This Website bar will already contain text that is grayed-out and might match the URL of your actual GitHub Page. That grayed-out text is inactive. Go ahead and paste in the URL of your GitHub Page anyway. Then click Save changes. You are done. Your GitHub Page should now be linked to your GitHub repository.
I made a .md file in my GitHub repo. The site automatic added a header with the link to the repo index page. I can't find any way to remove it.The repo name is called school The webpage is on /school/ss/1
Link to the code: Github
What it shows
Follow the "Layouts" instructions as shown on the Primer theme github site to edit website style: https://github.com/pages-themes/primer#layouts
Then, in your _layouts/default.html, remove lines 13-15 which add the title to your page
In their issues, I propose a simpler way to do this: https://github.com/pages-themes/primer/issues/21
I am using the 'Automatic Generator' of GitHub Pages, and I see it only generates a single index.html and other web resources.
How it works if I want to have a multi-page website generated from other markdown files?
You can get github to generate .html files from .markdown files by ensuring the top of the .markdown starts with the ---- block like this:
---
title: This will be used as the title-tag of the page head
---
hello
=====
**You are here!**
Found this here:
http://xlson.com/2010/11/09/getting-started-with-github-pages.html
Github will automatically create pages for you, if you include the markdown file.
index.html - yourname.github.io/project-name/
about.md - yourname.github.io/project-name/about
foo.md - yourname.github.io/project-name/foo
Tested this and working.
If you want to get into the really fun stuff - you need to get into Jekyll http://jekyllrb.com/
You pull the generated page, make any modification and addition you like (including adding new pages and links between the pages), then commit and push.
The generated single page helps you to make you start. You can duplicate its layout to generate other similar-looking pages by hand.
See Help.
Github Pages uses the Jekyll site generator which suports converting any number of markdown files to HTML for you, and applying the surrounding template via a layout file. See github's documentation on using Jekyll: https://help.github.com/articles/using-jekyll-with-pages
The trick is that you have to download a jekyll template/theme and include it in your gh-pages branch on your own (standard jekyll configuration), instead of just allowing Github Pages to auto-generate the one file using its own built-in themes.
GitHub Pages' automatic generator only generates one page.
You can add the new file directly, github page publishes all data (including data inside the subfolders) for you.
Just made gh-pages-generator - the utility to generate site with the navigation from multiple markdown files having links to each other.
"Github pages" hosts web page from index.md / readme.md as main page . However if you have an index.html file then it'll be hosted from html file.However , if you are trying to host a multi page website using "Jekyll themes" then Jekyll theme is not straightaway deployed in subsidiary pages .
Case 1) You are using markdowns to host your pages
index.md -> main page
page1.md -> page 1 of your website
..
so on
To generate a multiple page website using github page just give relative path to the required page without extension i.e.
make a button
Go to next page
And by clicking on this button you will be directed to page1 with jekyll theme deployed
GitHub wikis allow you to link to other pages in the wiki like so:
[[Wiki Page Name]]
However, I want to display different text than the wiki page name when making the link. Is there a way to do this? Am I linking to wiki pages all wrong?
Using the Markdown link syntax
[Link Text](WikiPage)
seems to work in the edit preview but not on the actual wiki page. At least for me the generated link is WikiPage instead of wiki/WikiPage and I get the famous GitHub 404.
However the MediaWiki syntax
[[Link Text|WikiPage]]
works for me, even for Markdown wiki pages.
GitHub by default uses Markdown syntax for the wikis so you can just do:
[Arbitrary Link Text](Wiki Page Name)
Check out Markdown and this blog post for more information about their wikis and the other markup syntaxes they support.
This solution has issues when you're on the home page because it creates relative URLs. Check out Sven's answer, below.
The internal-ref part is relative to your project. For wiki pages use:
[Page Name](wiki/Page-Name)
In the preview the link will be broken but when the page is saved it will work.
The most common use [Link Text](WikiPageURL)
The second way: [[Link Text|WikiPageURL]]
The third way, if you do not want to repeat and need to use the hyperlink several times: [Link Text] and at the end of the page use once [Link Text]:WikiPageURL
Check the wiki editor's help. It tells you:
To create a reference link, use two sets of square brackets. [my internal link][internal-ref] will link to the internal reference internal-ref.