Because this is a high quality theme that you didn't have to give away for free.

That's all.

I successfully added new .html page.

however, there is some discordance(??) problem.

https://adioshun.github.io/just-the-docs/docs/utilities/test/

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.

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.

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.

Checkboxes from GitHub flavoured markdown look a bit wonky:

They should look closer to:

See https://blog.github.com/2014-04-28-task-lists-in-all-markdown-documents/

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")?

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.

Add support for using data in collections for search

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 :)

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.

• Put the following front matter in a .md file:

--- 
layout: default
title: Getting Started
nav_exclude: true
search_exclude: true
--- 

• Page still shows up in nav

Expected behavior
Page is hidden from nav

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.

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>

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 [...]

I am trying to do inline links that appear on left navigation bar, so that when I click a link. It then scrolls to the heading level of 2.

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.

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.

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!

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
Jekyll doesn't export the theme assets to assets/.

To Reproduce
Steps to reproduce the behavior:

1. Make sure your Gemfile looks like this, for example:

   source "https://rubygems.org"
   ruby RUBY_VERSION
   
   gem 'jekyll', '3.8.5'
   gem 'just-the-docs', '0.2.3'
   

2. Add theme: "just-the-docs" to _config.yml.
3. Run bundle exec jekyll serve.
4. Go to http://localhost:4000

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:

• OS: Ubuntu 18.10.
• Browser: Chrome

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

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...

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: "- ";
    }

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.

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.

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!

greate theme,

but i met a issue when i use it.

the site title will break line if too long?

so any advices to fix it?

thanks.

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

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!

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?

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)>'

Describe the bug
When running htmlproofertest, if using nested nav with permalink , it gives a linking error to the childrens folder.

To Reproduce
Steps to reproduce the behavior:

1. Create a parent page with the permalink reference to the childs folder:

   ---
   layout: default
   title: Parent
   nav_order: 2
   has_children: true
   permalink: /childrens
   ---
   

2. Run the 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>

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.

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.

not top . thanks!

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.

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??

Im assuming you only support 2 levels of hierarchy here as strange things happen if you add pages with child that also have children

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

• All child pages are in an a integrator-guide subfolder
• The parent page front matter

---
layout: default
title: Integrator Guide
nav_order: 2
has_children: true
permalink: /integrator-guide
---

• Child pages front matter example

---
layout: default
title: Getting Started
parent: Integrator Guide
nav_order: 1
---

• While the left-hand nav is incorrect, if you navigate to the parent page /integrator-guide the TOC generated automatically on that page is correct and does show the right children

Expected behavior
Left nav contains the right children

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.

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!

I would like to add a link to an external gitbub page on the sidebar. How do I do that?

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...

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.

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.

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 %}

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.

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?

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 ?