carlosperate / jekyll-theme-rtd Goto Github PK

View Code? Open in Web Editor NEW

42.0 5.0 64.0 5.83 MB

Port of the Read the Docs theme to Jekyll to use with GitHub Pages.

Home Page: https://carlosperate.github.io/jekyll-theme-rtd

License: BSD 2-Clause "Simplified" License

Ruby 3.79% HTML 85.07% CSS 11.14%

jekyll-theme readthedocs rtd gh-pages github-pages github-pages-theme github-pages-template jekyll-template

jekyll-theme-rtd's Introduction

Read The Docs Theme for Jekyll and GitHub Pages

Port of the Read the Docs theme to Jekyll that can be used with GitHub Pages.

You can preview it in the user documentation:

The original Read The Docs theme was created for Sphinx, and so it is designed specifically for documentation.

Combined with GitHub Pages it's a great and easy way to document your projects!

Check out the quick start guide to see how easy it is to

🚧 Warning!

This theme is currently a Work-In-Progress but, while some things might be broken, it should be already usable.

Missing features are listed in the GitHub issues with the to-do label, and any known issues are listed with the bug label.

Contributions are very welcomed!

🗂️ Readme Contents

This README contains mostly the developer documentation to edit this theme.

To learn how to use this theme for your own website or docs check out the user documentation.

🚀 Using this theme with GitHub Pages
👩‍💻 Developer Documentation
👨‍👩‍👧‍👦 Contributing
⚖️ License

🚀 Using this theme with GitHub Pages

The fastest way to use this theme is with GitHub Pages, check out the Quick Start Guide from the user documentation.

👩‍💻 Developer Documentation

These instructions describe two different ways to to set up your environment to develop or edit this theme.

The theme is developed like a normal Jekyll site, and it can serve the documentation using the theme source code located here.

Run in a virtual machine with Vagrant

Vagrant provides an easy way to set up and manage a Virtual Machine with VirtualBox. With a single command you can automatically create the VM with all the dependencies required to build and sever this project.

There is a Vagrantfile included to run an Ubuntu VM with Ruby and Jekyll. To set-up everything and serve the website run:

$ vagrant up

The first time you run this command it will take a bit longer, as it downloads and installs everything. Subsequent runs will be much quicker.

This will serve the website at http://localhost:4000 with a hot-reload enabled, so any changes made on these files will trigger a rebuild.

Other Vagrant commands

To stop the virtual machine first press Ctrl+C to end the Jekyll process and execute in your terminal:

$ vagrant halt

You can also SSH into the virtual machine with:

$ vagrant ssh

Run locally with Ruby

This website has been developed using Ruby v2.5. You can install the dependencies with:

$ gem install bundler
$ bundle install

Build the docs using the remote theme

The Jekyll project here is configured with the root of this repository as the root of the website, so when it is built locally it will see all pages as being inside a "docs" folder, and therefore in the "docs" category in the left navigation bar and page URLs.

On the other hand the root of the website built and served with GitHub Pages is the "docs" folder, so the left navigation bar will show the child folder as categories and the URLs will be different.

For updating the theme documentation it can be useful to build and sever the docs folder with the same configuration as GitHub Pages. Of course, this would mean that the theme used will be the current snapshot of master on GitHub instead of the local files, but that is not important to just preview the docs.

To do this, add the following lines to the docs/_config.yml file:

plugins:
  - jekyll-remote-theme

Then execute Jekyll from the docs folder:

$ vagrant up --no-provision
$ vagrant ssh
(ssh session) $ cd /vagrant/docs
(ssh session) $ bundle exec jekyll serve --host 0.0.0.0 --watch --force_polling

Build the docs with MkDocs for comparison

As this theme has been ported from the MkDocs port, it can be useful to run MkDocs on the documentation markdown file and compare its output to the Jekyll output. A mkdocs.yml file is included to configure the project.

Pipenv has been used to manage Python dependencies:

$ pip install pipenv
$ pipenv install
$ pipenv run mkdocs build
$ cd _site_mkdocs
$ pipenv run python -m http.server 8080

👨‍👩‍👧‍👦 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/carlosperate/jekyll-theme-rtd.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

⚖️ License

The theme modifications to port it Jekyll can be seen here. This and all new features are released under the BSD 2-Clause "Simplified" License.

jekyll-theme-rtd's People

Contributors

Stargazers

Watchers

Forkers

schosterbarak billw2012 takehidesoh wootaik adamcatley javiertraseira voltairera stain traceaxil sohn3363 imoisharma benjamintemple jrpellicer skyl christodoulos elektrikakar lordlydican nur76n zhiyuanyao7 hautaklyttn michaelvdnest-forks erikhencier-h aklakan jczuurmond cinemataztic johnsunx1 burritojustice f-macfarlane95 hypyspectral moffkalast weber-agv ahornos terrance74liang bentraje bala-ceg abdelkaderm pam-d ucla-data-science-center jt14den danmanners lhumphrey guillaumelauzier josepablobermudezm 14385423 brytsknguyen thopri visualmicro evezeyl crollins18 qliangw ihm-tswow tswow tomoknetwork zabbixa idprojectgroup ibraheem-web caitlin-v-wilson nymbo raksha-shenoy itakea

jekyll-theme-rtd's Issues

License question

Hi,
I am building a little repo based on your instructions and theme (but I am not so familiar with the LICENSE usage).
My repo is more a place holder for information for me (but other people might find it useful)

So I added your license, in addition with mine, I am not sure if this is the way to do so. Your license for everything that has to do with the theme.
I want to use the license BSD 3 for the content of what I write (as I do not want that to be as recommendation for any product. My aim is purely informational)

Could you have a look if doing so complies with your license requirements?
https://github.com/evezeyl/logitech_MX_Keys_Linux_Memo/blob/main/LICENSE

Search box send the user to absolute url at domain root

Search queries go to /search.html?... instead of <site_url>/search.html?....

Add navigation list overwrite to config.yml

To set your own navigation list of links instead of adding all pages per directory.

When the page is at the top level the breadcrum is missing a ">>"

Github pages changes broke the media handling?

The current deployment on pages doesn't work:

https://carlosperate.github.io/jekyll-theme-rtd/

I get a similar but slightly different problem when I try:

https://skyl.github.io/bonsai/

I have a setup on a slightly older version of Github Enterprise that seemed to work fine yesterday .. hrm ..

Ability to add notes

Like Sphinx:

https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html#admonitions

Or like MkDocs:

https://mkdocs.readthedocs.io/en/stable/user-guide/configuration/#prebuild_index

Add highlight for search results

Looks like it might be enabled via URL query parameter:
https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html?highlight=sphinx

Search doesn't work at all.

I just get 404 page regardless of what I search for on the demo pages and my own.
My pages: https://sparker95.github.io/Vindicta/

"Edit on Github" shows with broken URL without the config entry

If the github URL has not been set in the _config.yml file the "edit on github" link should not appear if built with Jekyll, and should get the URL from the Github variable if built with GH Pages.

Right now, in GH Pages the link appears, but it is broken.

Format tables nicely

Not sure why, but tables are not currently formatted.

Jekyll output:

MkDocs output:

This is what the Read The Docs theme does:

https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#tables

Remove "edit on GH" for pages like search

As the title says.
The 404 page is actually defined in the docs folder, so that one is fine.

Navigation doesn't collapse unless I navigate to an anchor

Hello,
I have deployed this theme on GitHub pages for a project of mine: https://theprez.github.io/ServiceCommander-IBMi/

When the page loads, navigation isn't collapsed. However, if I navigate to an anchor on the page, for instance https://theprez.github.io/ServiceCommander-IBMi/#service-commander-for-ibm-i , everything gets collapsed as expected and looks great.

User error or theme defect? Any insight appreciated. Thanks for making this cool theme!

Add navigation_depth config for the left-side navigation TOC

To let the user control how many levels to show in the navigation tree on the left.

Right now hardcoded to 4.

Should be named navigation_depth to follow the ReadTheDocs config: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html

Logo is not showing up.

Hi there!

I am trying to build a website. Apparently all is working nicely but tthe logo is not:

This is my _config.yml file:

title: Mobile Robotics Blog
description: This blog will host the latest news regarding the development of the subjects practices
remote_theme: carlosperate/jekyll-theme-rtd

# Theme settings:
site_author: Diego García Currás
repo_url: "https://github.com/dgarcu/mobile_robotics_blog"
edit_on_github: true
github_docs_folder: true
logo: './docs/assets/img/logo.png'
site_favicon: './docs/assets/img/favicon.ico'
sticky_navigation: true
prev_next_buttons_location: bottom
search_enabled: true
hljs_style: github-gist

The favicon is showing up as expected, btw.

I think I followed the instructions in the docs, but apparently I am missing something. Maybe the issue is with the image. Here you will find my repo where the page is being built and deployed, just in case you want to take a deeper look. The img is located at the path ./docs/assets/img/logo.png of said repo.

Thanks in advance! Cheers!

Diego.