just-the-docs / just-the-docs Goto Github PK
View Code? Open in Web Editor NEWA modern, high customizable, responsive Jekyll theme for documentation with built-in search.
Home Page: https://just-the-docs.com
License: MIT License
A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
Home Page: https://just-the-docs.com
License: MIT License
Just tried to deploy this theme using
remote_theme: pmarsceill/just-the-docs
in the _config.yml
on Github - works like a charm. Love it! Thereafter I tried the same on a (hidden behind a firewall) Github Enterprise instance. I only got an unspecified error. I presume the instance has no external connectivity. I can deploy any of the build in themes.
What are the steps required to manually install this nice theme on a GHE instance?
Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
Describe the solution you'd like
A clear and concise description of what you want to happen.
Looking for main navigation anchor links
Anchor Links
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.
I have thought about editing the main nav html
Additional context
Add any other context or screenshots about the feature request here.
Would be good if the compiled css would be minified or at least have the comments stripped/use scss only comments. That way the site is more responsive...
Describe the bug
After following the structure recommended by the docs, the nav structure doesn't look right:
To Reproduce
Steps to reproduce the behavior using build 0.1.6 of the Gem
integrator-guide
subfolder---
layout: default
title: Integrator Guide
nav_order: 2
has_children: true
permalink: /integrator-guide
---
---
layout: default
title: Getting Started
parent: Integrator Guide
nav_order: 1
---
/integrator-guide
the TOC generated automatically on that page is correct and does show the right childrenExpected behavior
Left nav contains the right children
I successfully added new .html page.
however, there is some discordance(??) problem.
https://adioshun.github.io/just-the-docs/docs/utilities/test/
The Search box seems to be pretty unreliable to me. Sometimes it shows false positives, sometimes actual results are missing.
Example: On your site, type "searchsearch_enabled" to the search box.
As long as you type "searchsearch_en", there are matches. As you keep typing "abl", no more matches. When you type the trailing "ed", the matches come back.
Part of the story is that plenty of space characters are missing from search-data.json, e.g. whenever there's an explicit newline in markdown (to keep a sensible width of the source file), the two words become concatenated. That's how lines 14-15 of docs/configuration.md become "searchsearch_enabled", that's why searching for "abcdef" (present in ui-components/typography.md) doesn't give any match, etc.
Another part of the story is that the search engine must be buggy as well, for example not returning the match for the substring "searchsearch_ena". Another example: utilities/color.md contains the word "systemsized", this correctly appears in search_data.json, yet not found via the search box. It's quite easy to find other examples too.
I just updated to v2.0.0, thanks for the extra features!
On your doc site the pages with children have minimal content. However I have a lot of content so I add my own Table of Contents at the top. The additional mandatory table of contents at the bottom with links to the sub pages does not make much sense for my use cases, and is mostly redundant as the same links are already in the side bar.
An option to supress this per page would be nice.
Currently all pages will show up in the search results and there is no manual way to exclude a page from being indexed.
We use the pattern nav_exclude
to exclude a page from the navigation, we should have a search_exclude
to exclude a page from being indexed in search.
Checkboxes from GitHub flavoured markdown look a bit wonky:
See https://blog.github.com/2014-04-28-task-lists-in-all-markdown-documents/
Hi there! Thanks again for the epic template!
I am running into some errors on my side (I don't think it is a bug, but rather just a request to update the documentation).
Request:
Clarrify what a new user needs to do to deploy your theme on username.github.io.
Problem:
When I try to update the "url" in the config yml-file from your username (https://pmarsceill.github.io/) to mine (username.github.io), the page breaks.
title: Just the Docs
description: A Jekyll theme for documentation
baseurl: "/just-the-docs/" # the subpath of your site, e.g. /blog
url: "https://pmarsceill.github.io/" # the base hostname & protocol for your site, e.g. http://example.com
Could you please clarify for me what I need to change? or am doing wrong. I assumed if I update the url, it would work.
Thanks a lot :)
It would be great if we could manage multiple languages for our documentation
There should be a sticky language "switcher" button on the header.
And we could write the pages under docs/<language>/...
Btw, thanks for this beautiful site! I just love it and I am planning on using for my projects
Hi,
First of all, thanks for this lovely theme!
I uploaded a site based on this theme to GitLab, and received the following error:
$ bundle exec jekyll build -d public
[...]
Generating...
Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/dark-mode-preview.scss':
Invalid US-ASCII character "\xE2" on line 60
jekyll 3.8.5 | Error: Invalid US-ASCII character "\xE2" on line 60
ERROR: Job failed: exit code 1
The error message is misleading, the said file doesn't even contain 60 lines. Instead, the culprit is _sass/content.scss
which, on line 60, contains a Unicode "Bullet" character whose first byte is indeed 0xE2.
Adding
@charset "UTF-8";
to the top of _sass/content.scss
fixes this issue.
I'm new to all this Jekyll and stuff business, I have no idea what difference in configuration makes it apparently work for you on GitHub and also made it work for me locally, but causes failiure on GitLab. Anyway, if you agree that this is a proper fix, could you please apply it? Thanks!
Hi,
When the pages load, the keyboard Up and Down arrow do nothing. They scroll neither the left-side navbar, nor the right-side content area. You need to click on the text once for them to work.
Ideally I think the right-side main pane should receive the keyboard focus (or what is it called?) on page load so that it can be scrolled, like on most homepages. (I understand that with the two independently scrolling vertical panes the layout of this page is not like most pages out there.)
Do you happen to know how to do it? I spent like two minutes trying to figure out how to give "focus" to an element that's not input focusable by its nature, I came across tabindex=0 which I've tried to add to main-content-wrap or main-content, no success so far. Guess I should try a bit harder :) but I think you have more experience here.
I'm new to jekyll world, so this question might be stupid, I apologize ahead of time.
I created a fresh new project by using jekyll new myblog
, then changed the theme to just-the-docs, after running jekyll serve
, I observed that the 404.html
at source root directory got indexed into navbar unexpectedly. How can I exclude *.html
files from being indexed?
my 404.html
file (from jekyll's new project template):
---
layout: default
title: 404
---
<style type="text/css" media="screen">
.container {
margin: 10px auto;
max-width: 600px;
text-align: center;
}
h1 {
margin: 30px 0;
font-size: 4em;
line-height: 1;
letter-spacing: -1px;
}
</style>
<div class="container">
<h1>404</h1>
<p><strong>Page not found :(</strong></p>
<p>The requested page could not be found.</p>
</div>
Whenever I push files locally to my Github repo, I receive an alert notification with the following:
"We found a potential security vulnerability in one of your dependencies."
Upon opening the security alert further, the details reveal it is pertaining to the package-lock.json file in tandem with something called lodash.
I have no idea what this is, how to fix it, or how legitimate the severity the alert is. Any thoughts?
https://pmarsceill.github.io/just-the-docs/package-lock.json
This file seems to contain technical info that are none of the business of the site's readers. What do you think of adding it by default to _config.yml's exclude section (perhaps as wildcard "package*.json")?
Describe the bug
Breadcrumbs starts from parent instead of root, and the parent link in the breadcrum references the current page.
See: https://edouard-gv.github.io/ddd-java9/rappel-ddd.html
(Version of source code: https://github.com/edouard-gv/ddd-java9/tree/9f9297e4559a7661d724bce3926767015e296799)
Context
Using Github Pages with "Just the Docs" as a remote theme, as demonstrated in https://github.com/pmarsceill/jtd-remote, but with Pages site being built from the /docs folder in the master branch. It seems the only difference I see.
Im assuming you only support 2 levels of hierarchy here as strange things happen if you add pages with child that also have children
Dependabot can't resolve your Ruby dependency files.
As a result, Dependabot couldn't update your dependencies.
The error Dependabot encountered was:
Bundler::VersionConflict with message: Bundler could not find compatible versions for gem "safe_yaml":
In Gemfile:
just-the-docs was resolved to 0.2.1, which depends on
jekyll (~> 3.8.5) was resolved to 3.8.5, which depends on
safe_yaml (~> 1.0)
Could not find gem 'safe_yaml (~> 1.0)', which is required by gem 'jekyll (~> 3.8.5)', in any of the sources.
If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.
You can mention @dependabot in the comments below to contact the Dependabot team.
Is your feature request related to a problem? Please describe.
While vertical alignment does a lot, I have faced several situations where I had to horizontally align elements as well. This mainly occurs when dealing with images.
Describe the solution you'd like
I think it'd be nice to provide set of classes, similar to what is already there for vertical alignment but for Horizontal alignment. This could be simple .floatright
, .floatleft
, and .center
, or other more customizable options.
Describe alternatives you've considered
I am aware that I can technically define these myself and solve the problem but I thought it would be nice to natively add them to the theme as well.
Additional context
I'm not a CSS developer, I can start preparing a PR, but I don't think it'd keep up to the standard. However, if you think this is a good starting point, I can go ahead and start the PR, and leave the cleanup to you. π
Thanks for the them btw, it's awesome!
not top . thanks!
The links in the rendered markdown all start with http://
this prevents this theme from rendering on https sites.
Mixed Content: The page at 'https://docs.plantiga.io/' was loaded over HTTPS, but requested an insecure script 'http://docs.plantiga.io/assets/js/just-the-docs.js'. This request has been blocked; the content must be served over HTTPS.
If you use //
you can support both http and https. I have never built a theme before, but If you point me in the right direction, maybe I can submit a PR.
Describe the bug
When running htmlproofer
test, if using nested nav with permalink , it gives a linking error to the childrens folder.
To Reproduce
Steps to reproduce the behavior:
---
layout: default
title: Parent
nav_order: 2
has_children: true
permalink: /childrens
---
htmlproofer
command:
bundle exec htmlproofer ./_site \
--allow-hash-href \
--check-html \
--disable-external
Expected behavior
The command will return the following error:
- ./_site/parent.html * internally linking to /childrens, which does not exist (line 61) <a href="/childrens" class="navigation-list-link active">Parent</a>
Firstly, Thanks for your great share for this theme. I have built my own gh page based on it. ( matrixzj.github.io)
I want to improve search result based on page contents. I have tried keywords 'BBQ', nothing was shown in result. I have checked searched result json (https://matrixzj.github.io/assets/js/search-data.json) 'BBQ' should be included in https://matrixzj.github.io/docs/sa-keycaps/PhotoStudio/
How can I improve search result ?
im still getting build errors for github pages, this only started happening after dark theme was added.
Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/dark-mode-preview.scss':
Undefined variable: "$grey-dk-250". on line 12
Describe the bug
.md
page with nav_exclude
doesn't exclude the page from the nav.
To Reproduce
Steps to reproduce the behavior on version 0.1.6 of the Gem.
.md
file:---
layout: default
title: Getting Started
nav_exclude: true
search_exclude: true
---
Expected behavior
Page is hidden from nav
Hi. One more question :)
to use disqus, which file should I change?
I change the post.html
file as following.
---
layout: default
---
{{ content }}
<b>TEST</b>
{% include disqus.html %}
Nothing changed. Even the "TEST" text does not printed.
could you give me a help.
Thanks in advanced.
There is a minor layout bug in the theme: if the page is resized vertically, bullets of subpages in the navigation list appear above all other elements: https://www.dropbox.com/s/uuuiqdc7rukkqyt/9_l-prdq.png?raw=1
Looks like it's due to the position: absolute
set in the navigation.scss
.
.navigation-list-item {
&::before {
position: absolute;
margin-top: 0.3em;
margin-left: -0.8em;
color: $grey-dk-000;
content: "- ";
}
Describe the bug
Jekyll doesn't export the theme assets to assets/
.
To Reproduce
Steps to reproduce the behavior:
source "https://rubygems.org"
ruby RUBY_VERSION
gem 'jekyll', '3.8.5'
gem 'just-the-docs', '0.2.3'
theme: "just-the-docs"
to _config.yml
.bundle exec jekyll serve
.Adding --verbose
to bundle exec jekyll serve
doesn't result in any relevant output.
Expected behavior
The site is generated using the theme, just like GitHub Pages does (e.g., https://specs.relaynet.link/).
Screenshots
Desktop:
Additional context
In case it's relevant, here's the repo I'm trying to serve locally with this theme: https://github.com/relaynet/specs
Dependabot can't resolve your Ruby dependency files.
As a result, Dependabot couldn't update your dependencies.
The error Dependabot encountered was:
Bundler::VersionConflict with message: Bundler could not find compatible versions for gem "safe_yaml":
In Gemfile:
just-the-docs was resolved to 0.2.1, which depends on
jekyll (<= 3.8.5, >= 3.8.5) was resolved to 3.8.5, which depends on
safe_yaml (~> 1.0)
Could not find gem 'safe_yaml (~> 1.0)', which is required by gem 'jekyll (<= 3.8.5, >= 3.8.5)', in any of the sources.
If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.
You can mention @dependabot in the comments below to contact the Dependabot team.
I would like to add a link to an external gitbub page on the sidebar. How do I do that?
hey newbie here (yay), I have been getting build errors for my site. I am wondering how I properly assign version number for theme in my _config.yml. this is the error.
Your SCSS file
assets/css/dark-mode-preview.scss has an error on line 12: Undefined variable: "$grey-dk-250". For more information, see https://help.github.com/articles/page-build-failed-invalid-sass-or-scss/.
and this is my yml
`remote_theme: "bmlt-enabled/just-the-docs"
version: "0.2.0"
`
any help would be greatly appreciated. Thank you so much for all the work that you do as well.
I was wondering, would there be any chance of including some favicon code in _includes/head.html
?
Something like:
{% if site.favicon != nil %}
<link rel="shortcut icon" href="{{ site.favicon | absolute_url }}">
{% endif %}
I'm using this theme as a remote theme.
Is there any way to include an image (a logo for example) on the sidebar below the title?
btw, beautiful theme, thanks so much for making it free!
Dependabot can't resolve your Ruby dependency files.
As a result, Dependabot couldn't update your dependencies.
The error Dependabot encountered was:
Bundler::VersionConflict with message: Bundler could not find compatible versions for gem "safe_yaml":
In Gemfile:
just-the-docs was resolved to 0.2.1, which depends on
jekyll (<= 3.8.5, >= 3.8.5) was resolved to 3.8.5, which depends on
safe_yaml (~> 1.0)
Could not find gem 'safe_yaml (~> 1.0)', which is required by gem 'jekyll (<= 3.8.5, >= 3.8.5)', in any of the sources.
If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.
You can mention @dependabot in the comments below to contact the Dependabot team.
I rebuilt my site with the latest version (v0.2.2) and the search didn't seem to work. I changed my Gemfile.lock to build it with v0.2.1 and the search started working again. I changed it back, rebuilt and it was broken again.
I haven't had time to look into what changes were made, so I will update this when I have some time this weekend.
Getting error when running build through Gitlab CI.
Not sure if it is a Gitlab CI issue or if gem file issue
Running with gitlab-runner 11.5.0 (3afdaba6) on docker-auto-scale ed2dce3a Using Docker executor with image ruby:2.3 ... Pulling docker image ruby:2.3 ... Using docker image sha256:3ffc9af2681934d1ef6965c4688e4b657f401515a0f1fecd4b01e58fe4e4e879 for ruby:2.3 ... Running on runner-ed2dce3a-project-9932150-concurrent-0 via runner-ed2dce3a-srm-1546331225-08b428a0... Cloning repository... Cloning into '/builds/incent/api-docs'... Checking out a261ea13 as master... Skipping Git submodules setup $ bundle install Fetching gem metadata from https://rubygems.org/.......... Could not find http_parser.rb-0.6.0 in any of the sources ERROR: Job failed: exit code 1
Dear.
I'm new to github based webpage.
I added new cccc.md
and it looks work.
https://adioshun.github.io/just-the-docs/docs/utilities/cccc/
Now, I am trying to add new test.html (by convert jupyter.ipynb
to test.html
)
I just upload it on the same folder.
https://github.com/adioshun/just-the-docs/blob/master/docs/utilities/test.html
What should I do next? do I need to add front-matter
like the cccc.md
??
I added a _config.yml
file in my /docs
folder with the following content:
remote_theme: pmarsceill/just-the-docs
And now my GitHub Pages deployment is failing with the following error message:
Your SCSS file `assets/css/just-the-docs.scss` has an error on line 5: File to import not found or unreadable: ./normalize.scss/normalize...
Is there any other step I'm missing? The install steps from the readme seem to be meant for local development, not GitHub.
Plus, I cannot see how a Gemfile
would change anything since the only place normalize.scss
is referenced in is the package.json
.
Perhaps it needs to be added as a real dependency and not just a development dependency?
Any help is greatly appreciated!
Because this is a high quality theme that you didn't have to give away for free.
That's all.
Fixing #48 introduced a bug that caused the page to scroll the content down to the main
div by default instead of loading at the top of the content pane.
I'm getting the following error with version 0.2.2 and Ruby 2.3.1 (via rbenv)
bundler: failed to load command: just-the-docs (/Users/michaelrumpf/.rbenv/versions/2.3.1/bin/just-the-docs)
NameError: undefined local variable or method `amp' for main:Object
Did you mean? cmp
/Users/user/workspace/just-the-docs-0.2.2/lib/tasks/search.rake:17:in `block (3 levels) in <top (required)>'
/Users/user/workspace/just-the-docs-0.2.2/lib/tasks/search.rake:11:in `open'
/Users/user/workspace/just-the-docs-0.2.2/lib/tasks/search.rake:11:in `block (2 levels) in <top (required)>'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:273:in `block in execute'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:273:in `each'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:273:in `execute'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:214:in `block in invoke_with_call_chain'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/2.3.0/monitor.rb:214:in `mon_synchronize'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:194:in `invoke_with_call_chain'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/task.rb:183:in `invoke'
/Users/user/.rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/rake-12.3.2/lib/rake/application.rb:160:in `invoke_task'
/Users/user/workspace/just-the-docs-0.2.2/bin/just-the-docs:15:in `<top (required)>'
/Users/user/.rbenv/versions/2.3.1/bin/just-the-docs:23:in `load'
/Users/user/.rbenv/versions/2.3.1/bin/just-the-docs:23:in `<top (required)>'
Add support for using data in collections for search
Dependabot can't resolve your Ruby dependency files.
As a result, Dependabot couldn't update your dependencies.
The error Dependabot encountered was:
Bundler::VersionConflict with message: Bundler could not find compatible versions for gem "safe_yaml":
In Gemfile:
just-the-docs was resolved to 0.2.1, which depends on
jekyll (~> 3.8.5) was resolved to 3.8.5, which depends on
safe_yaml (~> 1.0)
Could not find gem 'safe_yaml (~> 1.0)', which is required by gem 'jekyll (~> 3.8.5)', in any of the sources.
If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.
You can mention @dependabot in the comments below to contact the Dependabot team.
Describe the bug
Website fails to serve from GitHub pages. I get this error instead
Your site is having problems building: A file was included in /_layouts/default.html that is a symlink or does not exist in your _includes directory. For more information, see https://help.github.com/en/articles/page-build-failed-file-is-a-symlink.
Expected behavior
Website serves correctly save as Jekyll serve on GitHub.
Thank you for taking the time to make and share this theme; it's fantastic.
I'm trying to follow your instructions for Customization and it says:
To customize your siteβs aesthetic, open _sass/custom/custom.scss in your editor to see if there is a variable that you can override.
How do you open specific scss files if the theme is installed as a gem? I'm working locally right now so I have a vendor/bundle
folder that contains the gems, but obviously editing those files won't persist once I deploy.
I also tried to follow the Jekyll instructions for Customizing CSS and HTML:
1 Create a file called /assets/css/style.scss in the root of your site's repository.
2 Add the following content to the top of the file, exactly as shown:--- --- @import "{{ site.theme }}";
Following those instructions, however, I get the following error:
Conversion error:
Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
File to import not found or unreadable: just-the-docs. Load paths:
/<root>/vendor/bundle/ruby/2.3.0/gems/just-the-docs-0.1.6/_sass
/<root>/vendor/bundle/ruby/2.3.0/gems/just-the-docs-0.1.6/_sass on line 1
Any insight or help would be greatly appreciated.
Is your feature request related to a problem? Please describe.
No problem really.
Describe the solution you'd like
I would like to be able to center images on the page. I have lots of sequence diagrams that are tall and they look better (to me) centered instead of left-aligned.
Describe alternatives you've considered
Haven't tried any alternatives.
Additional context
Example page: https://level3-rest.github.io/patterns/profiles/nexus
On Mobile, long headers are not wrapped, causing the menu and rest of the content to be scaled incorrectly. It seems like there is something not working with the css. I can provide an example if needed...
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.