rundocs / jekyll-rtd-theme

Just another documentation theme compatible with GitHub Pages

jekyll-rtd-theme

Just another documentation theme compatible with GitHub Pages

What it does?

This theme is inspired by sphinx-rtd-theme and refactored with:

• @primer/css
• github-pages (dependency versions)

Quick start

remote_theme: rundocs/jekyll-rtd-theme

You can generate with the same files and folders from rundocs/starter-slim

Usage

Documentation that can guide how to create with Github pages, please refer to rundocs.io for details

Features

• Shortcodes (Toasts card, mermaid)
• Pages Plugins (emoji, gist, avatar, mentions)
• Auto generate sidebar
• Attribute List Definitions (Primer/css utilities, Font Awesome 4)
• Service worker (caches)
• SEO (404, robots.txt, sitemap.xml)
• Canonical Link (Open Graph, Twitter Card, Schema data)

Options

name	default value	description
title	repo name
description	repo description
url	user domain or cname
baseurl	repo name
lang	en
direction	auto	ltr or rtl
highlighter	rouge	Cannot be changed

# folders sort
readme_index:
  with_frontmatter: true

meta:
  key1: value1
  key2: value2
  .
  .
  .

google:
  gtag:
  adsense:

mathjax: # this will prased to json, default: {}

mermaid:
  custom:     # mermaid link
  initialize: # this will prased to json, default: {}

scss:   # also _includes/extra/styles.scss
script: # also _includes/extra/script.js

translate:
  # shortcodes
  danger:
  note:
  tip:
  warning:
  # 404
  not_found:
  # copyright
  revision:
  # search
  searching:
  search:
  search_docs:
  search_results:
  search_results_found: # the "#" in this translate will replaced with results size!
  search_results_not_found:

plugins:
  - jemoji
  - jekyll-avatar
  - jekyll-mentions

The license

The theme is available as open source under the terms of the MIT License

jekyll-rtd-theme's Issues

Mathjax isn't work

Describe the BUG
Looks like it's working fine hosted by Github Pages like demo site.
But, I can't use latex in my site...（hosted by Google App Engine）

I can confirm that adding script tags directly to the page works fine, so I feel that dynamic script loading is not working.
https://github.com/rundocs/jekyll-rtd-theme/blob/develop/_includes/common/mathjax.liquid

env

• Gem based
• Hosted by Google App Engine (not Github Pages)

To Reproduce

1. Copy starter templete repo
2. Run git clone from local machine
3. Add mathjax file
4. Run make command
5. Run make server command

Site link or Repository
Sorry, it is a private repository and cannot be shared.

Latex equation notation does not render

Describe the BUG

When adding the following latex notation equation: $\hat{B}1 \pm t{\frac{\alpha}{2},n-2} \cdot s_{B_1}$ it does not render and instead displays as normal text.

Would this be a feature that can be added to the theme?

To Reproduce

Add any latex notation to a page and commit to build the page.

Site link or Repository

https://github.com/spestana/data-analysis

RFE: Allow configurable name in breadcrumb

Hi,
Actually breadcrumb is showing page.name, which might be cool but sometimes it's better to use page.title which can be defined in the frontmatter.

Would be nice to allow theme to be configurable to use one or the other (even defaulting to actual page.name).

Sidebar Title Not Clickable

For the automatically generated nested sidebar, the files are clickable, which means they can be clicked to referring to their correct document without any problems. However, the Folder Title bar is not clickable for their own path.

For example, if the generated sidebar is

• TEST DOCUMENT

  1. Markdown Elements
  2. Album Images

• THIS IS AN INCREDIBLY LONG CAPTION FOR A LONG MENU

  1. I'm folder1
  • file1
  • file2

Except Two title bar, TEST DOCUMENT & THIS IS AN INCREDIBLY LONG CAPTION FOR A LONG MENU, all others are clickable.

This is pretty odd when those Title bar can be accessed by breadcrumbs, but cannot be reached by its own path.

Possible solution:

Inside the file _includes/extend/toctree.liquid line 11, change it to:

<p class="caption"><span class="caption-text"><a href="{{ dir.url | relative_url }}">{{ dir.title | default: dir.url }}</a></span></p>

Correspondingly, to make it consistent, add the new CSS style in the file _sass/jekyll-rtd-theme.scss:

/* fix folder link, no performance changes on the original style*/

.wy-menu-vertical p.caption span a {
    color: #55a5d9;
    font-size: inherit;
    padding: 0px;
    display: inline;
    line-height: unset;
    text-decoration: inherit;
}

Suggestion To Clean Up Contents In .gitignore File

Reason

This package is used for website generating, every bite inside its directory matters, if user wants to exclude some files, they can have their own way to set those exclusions before they start building, say, inside _config.yml file, so it is unnesscary to help user pre-set those ignores, especially when those settings may cause git file transferring problems.

Potential Problem

Inside current .gitignore file, it has the entries like

*.gem
*.whl

However, it has the great possibilities that user will happen to have some source files with the same file extensions that git ignores, then it will make differences between local & github-pages compiling, when no attention paid to .gitignores.

And I highly suspect that it may be the same reason that you removed entry *.html in early version's, because you are having _include/extra/footer.html & _include/extra/head.html files.

My Personal Complaining

Well, this can also be an example to show what I have struggled for.

I have two different and separated reporsitories for this package, they contain:

Repo.:               My github.io                 My Fork
Usage:                [gh-pages]                 [rundocs]

Core codes:           Up to date                 Up to date
CSS Format:           Formatted                  Compressed
.gitignore:            *.html                       (x)

Like above shows, every time whenever I committed changes of the package core codes, my github.io always complained some liquid files were missing, it cannot work as I expected in my local building. As a result, it took me more than two hours to find the reasons.

Reason: because of the *.html settings, the git simply skipped the full _include/extra folder when makes comparisons.

With the help of local .gitignore file, it will be very convenient to make commits to rundocs git official reporisitory, however, it is highly possible that the user may have any files happen to match any one of entry in default .gitignore settings, thus as a consequence, it will ruin github.io page renderings.

Alternative Solutions To git-ignores

You can set those settings as the global ignores when you are doing developments, like in ~/.gitignore or ~/.config/git/ignore or ~/.gitignore_global.

Link: global-gitignore

Once again, this package is not a one time build-to-use package, it dynamically updates whenever the server starts running.

As a conclusion, please clean up the contents inside .gitignore file, thank you!

Breadcrumbs showing filename instead of title

The breadcrumbs are showing the filename instead of the title defined in the file.

Open a page and see that the breadcrumbs contains the filename

For example on your own test site when opening https://jekyll-rtd-theme.rundocs.io/test/markdown.html, the breadcrumbs show /test/markdown.md instead of /test/Markdown Elements.
This was working fine in version 1.1.7.

Btw, I really like the theme.

master

Custom.scss is broken

Hi, one of the changes that were made yesterday broke the custom.scss feature. It no longer takes effect. Thanks.

Text lost after pre

Describe the BUG
text lost after pre

To Reproduce
https://rundocs.io/writng/mermaid.html

Add test process action!

"Edit on GitHub" link confusion

Describe the BUG

The "Edit on GitHub" link is not always correct, especially when the theme is set up as a remote_theme.

While this could be considered an issue with the Jekyll GitHub MetaData plugin, the fact that those links are still displayed in these situations is build into this theme.

For example: both the "Search" as well as the "404" pages show an "Edit this page" link which links to files which don't exist in the project directory, but only in the remote theme:

To Reproduce

• Set up a site with this repo as the remote theme: remote_theme: rundocs/jekyll-rtd-theme
• Add some pages
• Use the search form at the top of the side bar
• Click the "Edit" link at the top of the search results page and see a 404

Site link or Repository
not yet public

Why make test and test_long directory as article director? This seems wired.

Can I customize article directory to another directory? Such as _posts directory.

Impossible to use several Admonition Cards of the same type on the same page

Hello!

Reproducing:
The issue is the same with any type of Admonition Card.
Just make a page containing several Admonition Cards of the same type.
Sorry, I have no idea how to insert a markdown in a markdown, so I made a screenshot just in case ^^'
https://www.dropbox.com/s/h9h3438uzlt6r4e/Screenshot%202020-08-18%20at%2017.56.49.png

Expected behavior:
The site shows 2 blocks of type note with different text.

Actual behavior:
2nd (and all consequent) note(s) will have the same text as 1st one.
https://www.dropbox.com/s/6zqqux2qwnt98mo/Screenshot%202020-08-18%20at%2017.59.21.png

Unknown tag 'github_edit_link' included

Describe the bug
A clear and concise description of what the bug is.
Unknown tag 'github_edit_link' included

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

question - pages opt out

Hi, Thank you for this theme.
Is there a builtin way to work locally instead of providing a remote?

Have tried removing relevant dependencies such as jekyll-github-metadata but keep encountering errors.

Thanks!

Custom page ending and logo

Hello in version 1.1.7 it was still possible to:

• Specify the logo using the logo: attribute in _config.yml file
• Custom page ending using the author: attribute in _config.yml file
• Have the title in the breadcrumbs instead of the file name

Are there plans to bring these things back? This is holding is back from updating to the new version of this wonderful theme ...

CSS

AWESOME work fixing the search !!!! 👏

With the latest build i now have a issue with the CSS all of my css changes local are not getting called and it actually is going out and pull cdn.jsdelivr.net :( i have updated the CSS in the theme but it never gets called now.

How can i get around it calling the cdn.jsdelivr.net to pull in the css and js ? my color is set to b06cb1 for the background however you can see in the screenshot it is never getting called :(

Analytics behind a flag

Describe the BUG
Version 1 had analytics as an add-on. There doesn't seem to be an easy way to turn them off anymore.

I'd like to not send all my users data to some external site I don't control.

For now I'll probably rip the relevant code out of the javascript here

Toast Cards Cached

So I am having trouble when I have two or more of the same toast card type.
For example, if I make a note (with any type of content) it will display perfectly, but then if I make another note with different content, it will display the exact content of the first one and not the content I set it to display.

I rechecked your site at Link but it seems like you aren't having this issue yourself here.

Also, styling doens't work from within the toast cards.
Here is a picture to show the issue and the actual markdown:

Let me know if you would like more information.

The TOC has files listed first and directories listed post that

Currently In the table of content, the files are listed first and directories are listed after that.
This is not ideal.
It would be if we can have the folders listed in the middle of files as defined by the sort order

All customisations are gone...

All the customisations on the site have disappeared. Something else changed? @saowang

Search result prev and next display

Config settings to toggle copyright

A feature to toggle copyright will be great.

Some pre code to markdown, mobile header margin

Question about Toast Cards

First, really thank you for good theme. And this is first time for me to use CSS and Jekyll, so my question might be quite basic or unclear. Please excuse me.

I want to add another Toast Notes template, whose name is ".math" with background color as gray.

So I made math.liquid file in shortcodes folder, by changing inside of danger.liquid file from danger to math.

And I edit shortcodes.liquid, _variables.scss, and toasts.scss, each for adding .math function in assign shortcodes, adding $theme-gray, and adding .math function in toasts.scss. I made ,math function by copy and paste danger function, and just change its color variable to theme_gray, so I don't think there was error.

After this, .math function works as Toast Notes, but its background color is completely white, and color of title word "math" is white also. I keep looking other files and codes, but I can't find what's the problem and what I need to edit. Could you give me a help?

Primer css refactor the origin theme

Comparing changes: https://github.com/rundocs/jekyll-rtd-theme/compare/debug

NavBar compressing in downloaded theme, different than on rundocs.io website

Hi,

I'm creating Jekyll-based docs website for offline use (not hosted on GitHub). To get started, I created my Jekyll site basically as a mirror of the rundocs.io repository using the latest 1.1.0 release of jekyll-rtd-theme. When I run my version, the navigation on the left is compressed, and doesn't show the entire table of contents like it does on the rundocs.io website, and collapses unused sections. Showing the table of contents all at once is desirable. All of the config files and Gem files are identical to the rundocs.io repository.

Is this a difference in the CSS or JS with the repository? When I look at the source, it references the same CSS file from https://cdn.jsdelivr.net.

Thank you :)

Improve documentation

Admonition Card and page path formatting issue

Describe the bug
A change must have been made recently that's causing this.

Admonition Cards, and the page path at the top are no longer appearing properly (see https://mountain-hydrology-research-group.github.io/data-analysis/modules/week5.html)

appearance now:

previous, correct appearance:

, and attached images)

To Reproduce

1. I had cached versions of github pages using the jekyll-rtd-theme still showing the correct previous behavior (second image above)

• https://mountain-hydrology-research-group.github.io/data-analysis/modules/week5.html
• https://rundocs.github.io/jekyll-rtd-theme/test/admonitions.html

2. Refreshing these pages so as to view a current version (first image above)

Expected behavior
Adminition cards and page paths should appear as they did previously

Desktop (please complete the following information):

• OS: Windows 10
• Browser: Firefox 80.0.1 (64-bit)

Update content TOC to nest TOC!

jekyll-rtd-theme/_includes/assets/common.js

Lines 10 to 26 in 1b763b7

	/* generate content toc */
	$(".wy-menu-vertical li.current").append(function() {
	let level = parseInt($(this).attr("class").match(/toctree-l(\d+)/)[1]) + 1;
	let toc = ["<ul>"];
	/* let sort = parseInt(this.dataset.sort); */
	$(".document").find("h2,h3,h4,h5,h6").each(function() {
	toc.push(`<li class="toctree-l${level}"><a class="reference internal" href="#${this.id}">${$(this).text()}</a></li>`);
	});
	toc.push("</ul>");
	/* return is apend */
	if (toc.length == 2) {
	return "";
	} else {
	return toc.join("");
	}
	});

Custom scss or script

Starting about 12 hours ago the scss and script had stopped working. Went back to the basics and tried forking the starter-slim repo and adding the following code as found to the _config.yml as noted in the rundocs documentation and the scripts do not run. 2 days ago were working fine. Now all my css and nav width changes are not loading when the page loads :(

https://rundocs.io/configuring/custom.html

via _config.yml:

script: |
alert("it");
alert("works!");

scss: |
.wy-nav-content-wrap{background:#fcfcfc}
.wy-nav-content-wrap .wy-nav-content{max-width:none}

Dependabot can't evaluate your Ruby dependency files

Dependabot can't evaluate your Ruby dependency files.

As a result, Dependabot couldn't check whether any of your dependencies are out-of-date.

The error Dependabot encountered was:

Bundler::Dsl::DSLError with message: 
[!] There was an error parsing `Gemfile`: 
[!] There was an error while loading `jekyll-rtd-theme.gemspec`: No such file or directory @ rb_sysopen - _includes/reset/version.spec. Bundler cannot continue.

 #  from /home/dependabot/dependabot-updater/dependabot_tmp_dir/jekyll-rtd-theme.gemspec:1
 #  -------------------------------------------
 >  version = File.new("_includes/reset/version.spec", "r")
 #  
 #  -------------------------------------------
. Bundler cannot continue.

 #  from /home/dependabot/dependabot-updater/dependabot_tmp_dir/Gemfile:3
 #  -------------------------------------------
 #  
 >  gemspec
 #  
 #  -------------------------------------------

View the update logs.

fluid: true breaks the site's responsiveness

Pages are not responsive if fluid: true. This is what it looks like from a phone.

Is it possible to correct this at all?

Side Nav and Search Box colour

I was wondering if it is possible to change the background colours of the side-nav and search box?
I attempted this by overriding theme.css in my project but it didn't take effect - https://github.com/rundocs/jekyll-rtd-theme/blob/master/assets/css/theme.css

Would you consider adding a setting for this, considering it is very important to use custom branding colours? Thanks

The target CSS classes are:

.wy-side-nav-search {
	display: block;
	width: 300px;
	padding: .809em;
	margin-bottom: .809em;
	z-index: 200;
	background-color: **#custom-colour-code**;
	text-align: center;
	color: #fcfcfc
}

and

wy-nav-side {
	position: fixed;
	top: 0;
	bottom: 0;
	left: 0;
	padding-bottom: 2em;
	width: 300px;
	overflow-x: hidden;
	overflow-y: hidden;
	min-height: 100%;
	color: #9b9b9b;
	background: **#custom-colour-code**;
	z-index: 200
}

Quick start links are dead (404)

Describe the BUG
Quickstart section found on the home page https://jekyll-rtd-theme.rundocs.io/ are dead

To Reproduce

Links found on the page currently:

• Generate: https://github.com/rundocs/starter-slim/generate
• rundocs/starter-slim: https://github.com/rundocs/starter-slim/

Site link or Repository

using-with-github-enterprise

Hi,

theme works fine, however all links generated (e.g the edit button) always point to github.com

I followed http://jekyll.github.io/github-metadata/configuration/#using-with-github-enterprise
and set _config.yml properly (to my understanding)

repository: myorg/documentation
PAGES_API_URL: "https://api.github.my.corp"
PAGES_GITHUB_HOSTNAME: "https://github.my.corp/"
OCTOKIT_API_ENDPOINT: "https://api.github.my.corp"
OCTOKIT_WEB_ENDPOINT: "https://github.my.corp/"
PAGES_PAGES_HOSTNAME: "https://github.my.corp/pages/"

still all goes to github.com ☹️, edit or also the lower left menu with hp, issues, dl

"Header 1" level headings are not included in Index pane (Test sample site shows this)

Describe the BUG
"Header 1" level headings are not included in Index pane (Test sample site shows this)

To Reproduce
Generate the Test documentation which contains level one headings # Header 1

Site link or repository
https://montewood.github.io/test/markdown.html#header-2

Search feature is not working

Describe the bug
When you perform a search it does not return any results. This is the main feature of the template but only pulls back blank results. Just forked most recent files and can reproduce the issue.

To Reproduce
Steps to reproduce the behavior: Try searching for anything and no results are displayed

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
To see results of what the user is searching for

Screenshots
n/a

Desktop (please complete the following information):

• OS: Win10
• Browser chrome
• Version 85.0.4183.102 (Official Build) (64-bit)

Smartphone (please complete the following information):

• Device: multiple devices tried all produce the same a blank page when searching
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
LOVE the template great work just need to get the main feature working again :)

Usage

Hi, beautiful theme.
I’m a newbie to JekyII, is there any documentation that can guide how to create a Github page with this theme?

Sincerely

Custom CSS and SCSS no longer override theme

Describe the BUG
Custom CSS and SCSS no longer overrides the theme's.
I had some custom CSS and SCSS inside of the _includes/assets folder of my repository that affected the site. It worked well up until a day or two ago. I did not make any changes to my code during this time.

To Reproduce
Try overriding the theme's styling with a .scss file as per instructed in the documentation.

Site link or Repository
https://github.com/Aidenjn/bogl-docs

Feature request: respect in show_sorted in side bar

Based on the information from these docs: https://rundocs.io/configuring/sidebar.html, setting show_sorted: false in _config.yml is supposed to "turn off the order prefix".

But it appears that this only works for the TOC tree, not for the sidebar menu, which still shows the numbers as a page title prefix.

As the information about the show_sorted option was shown on the "Sidebar" configuration page, I expected it would work for the sidebar too.

Bug

Describe the BUG

To Reproduce

Site link or Repository

Sidebar sort order

Describe the BUG

Given a directory layout set up like so:

project root
 |- Sniffs
    |- Classes
    |- Constants
    |- ....
    |- MethodUse
    |- ....

Where each of these folders contains a README.md file with the following contents and one or more additional markdown files:

# DirectoryName

{% include list.liquid all=true %}

I would expect these directories to show alphabetically sorted in the side bar, and they do, except for this one folder MethodUse, which appears at the top of the submenu, completely out of the alphabetic order. (red color added to highlight the problem)

And yes, I have verified that there is no front matter with a sort in the Sniffs/MethodUse/README.md file.

Relevant parts from the _config.yml:

remote_theme: rundocs/jekyll-rtd-theme

readme_index:
  with_frontmatter: true

To Reproduce

Site link or Repository
not yet public

If it is not built from the github repo, errors occurred

Requesting Guidance on Locally Modifying Style Elements in rundocs / jekyll-rtd-theme

Dear Sowang et al.

I've been enjoying working with your GitHub Pages "RDT-style" template for some tutorial and support pages for our students.

I've made progress in making some small modifications off of your original template while still sourcing and crediting your work as a "remote theme" in the _config.yml file.

However, while I have made progress in making small tweaks with the liquid files, and directly adding them to the file tree on my github host site (link below), I am having difficulty with modifying scss files in a manner that makes the pages compliant with our new university "branding" policy ("for which all that is not forbidden is mandatory."), such as the right shade of blue and specific fonts.

I've modified the counterparts in your directory trees for _font-faces.scss, _variables.scss, and the style.scss following a number of google and stack-overflow searches and I have not been able to make these changes "stick."

Can there be some simple instructions for those of us who are new at this sort of thing to "tweak" your themes while maintaining the good work you've put into it?

For reference my hot-mess of a page is here:

• GitHubRepo: https://github.com/wjcapehart/AES_CEE_Python
• Rendered Pages: https://wjcapehart.github.io/AES_CEE_Python

Much obliged and thanks for your patience.
Bill Capehart
SD Mines

Failing Search

@saowang it might be worth taking a closer look at the search. I have had my site up for nearly a day and it's still not returning any search result. Is it expected? Should it be on by default?

Feature request : Turn off the sidebar when printing

Hi ! Your theme is so great !
It's simple and functional.

Let me make one feature request.

• The sidebar should not be displayed when printing or exporting PDF.

I hope you will consider implementing it.

custom png files

Hello,

I am using screenshots for documentation and would like to know how do I add/override custom .png files.

Settings and search

Hi is it possible to hide edit on github, the sidebar footer, please?

Also, the search is not working

Performance improvements for generating the sidebar

It's a very nice theme but unfortunately the build performance on larger sites is quite poor due to using Liquid for generating the sidebar and the TOC. I created a plugin to deal with this. Please take a look at my fork if you are interested:

https://github.com/johnnybaloney/jekyll-rtd-theme#about-the-fork

It's a POC hence no PR and may still need some extra polish, especially that this is my first encounter with Ruby (or Jekyll for that matter!), but seems to be working ok.