@parkr @mattr- In response to @ashmaroli's request on Jekyll-talk, I suggested versioned documentation. I was already aware of the jekyll-docs gem in this repo, which supports offline browsing of various versions of the Jekyll docs. But when browsing on the web, it seems to me very odd that those versions of the docs aren’t available online too. Couldn’t the Jekyll docs website simply serve all the sites built by jekyll-docs, at URLs such as https://jekyllrb.com/4.2.2?

@ashmaroli responded:

To host a versioned docs at jekyllrb.com, we may need to move the source for jekyllrb.com into a new repository. Please open an issue at the GitHub repository and ping parkr and mattr- for their take on the idea.

More generally, I also suggested to build versioned docs websites using Jekyll. The lack of direct Jekyll support for building versioned docs seems surprising on GitHub, where the focus is on version control! The versions-jekyll repo shows how developers can set up versioned docs using Jekyll; perhaps use of GitHub Actions and templates could simplify that approach?

In any case, various themes in other ecosystems do support versioned docs directly. The answer to a relatively recent request for help about support for versioned docs was to migrate the website from the Jekyll-based Just the Docs theme to Read the Docs…

@ashmaroli responded:

Currently, Jekyll simply takes one source of truth and builds an output out of it. So to build an doculibrary of multiple versions, you would need to maintain multiple versions of sources in different directories to get one mega Jekyll build run. I don’t see how it is difficult for users to use existing Jekyll functionality to set up a versioned-docs with a centralized GH Action.

It may not be so difficult (at least for expert users with experience of creating GH Actions). But I think it involves quite a lot of design considerations, as well as robust implementation. For example:

1. Should the sources of different doc versions be directories, collections, or branches?
2. Can (and should) unchanged doc source files be shared between versions?
3. Should version labels be semantic or arbitrary?
4. Can searches (e.g., using lunr.js) be restricted in the browser to a range of versions?
5. Can the contents of a version be updated after it has been built/published/released?
6. Should a versioned docs repo always be related to some code repo, or can it be independent of other repos?
7. Should users without GH Actions expertise be able to convert an unversioned docs repo to be versioned?
8. Etc.

I guess you already considered many such questions when creating this repo. For the offline Jekyll docs, some of the above questions have obvious answers, and some are irrelevant. But if you were to design and implement general support for using Jekyll to build online versioned docs, the versioned Jekyll docs might be simply an exemplary instance of it. And we might avoid each theme developer¹ needing to design and implement their own variant of versioned docs.

After open the issue jekyll-docs gem not found in jekyll repository I install the jekyll-docs gem in my computer but when I run jekyll docs it return the follow error:

it turns out some links in docs are still pointing to the website https://jekyllrb.com

for example, in my local docs,

docs -> Installation points to https://jekyllrb.com/docs/installation/

       <option value="https://jekyllrb.com/docs/installation/">
        Installation
       </option>

jekyll-docs seems to work only on Ruby 2.1.

Ruby 2.4

❯ ruby -v
ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin16]

❯ gem install jekyll-docs -v 3.6.2.0
Fetching: jekyll-docs-3.6.2.gem (100%)
ERROR:  While executing gem ... (Errno::EACCES)
    Permission denied @ rb_sysopen - /Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/jekyll-docs-3.6.2/lib/jekyll.rb

Ruby 2.3

❯ rbenv local 2.3.3
❯ ruby -v
ruby 2.3.3p222 (2016-11-21 revision 56859) [x86_64-darwin15]

❯ gem install jekyll-docs -v 3.6.2.0
Ignoring rainbow-2.2.2 because its extensions are not built.  Try: gem pristine rainbow --version 2.2.2
Fetching: jekyll-docs-3.6.2.gem (100%)
Successfully installed jekyll-docs-3.6.2
1 gem installed

❯ jekyll docs
Ignoring rainbow-2.2.2 because its extensions are not built.  Try: gem pristine rainbow --version 2.2.2
You must install the 'jekyll-docs' gem version = 3.6.2 to use the 'jekyll docs' command.

❯ gem list docs
Ignoring rainbow-2.2.2 because its extensions are not built.  Try: gem pristine rainbow --version 2.2.2

*** LOCAL GEMS ***

jekyll-docs (3.6.2)

Ruby 2.2

❯ ruby -v
ruby 2.2.7p470 (2017-03-28 revision 58194) [x86_64-darwin16]

❯ gem install jekyll-docs -v 3.6.2.0
Fetching: jekyll-docs-3.6.2.gem (100%)
Successfully installed jekyll-docs-3.6.2
1 gem installed

❯ jekyll docs
You must install the 'jekyll-docs' gem version = 3.6.2 to use the 'jekyll docs' command.

~
❯ gem list docs

*** LOCAL GEMS ***

jekyll-docs (3.6.2)

Ruby 2.1

🎉

❯ rbenv local 2.1.10
❯ ruby -v
ruby 2.1.10p492 (2016-04-01 revision 54464) [x86_64-darwin15.0]

❯ gem install jekyll-docs -v 3.6.2.0
Fetching: jekyll-docs-3.6.2.0.gem (100%)
Successfully installed jekyll-docs-3.6.2.0
1 gem installed

~ 17s
❯ jekyll docs
Configuration file: none
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Anyone else reproduce this?

When I run the jekyll docs cmd after installing the gem I still get an error message. Is there an integration step I'm missing?

$ jekyll docs
You must install the 'jekyll-docs' gem to use the 'jekyll docs' command.
$ gem install jekyll-docs`
[...]
$ gem list --local

*** LOCAL GEMS ***

[...]
jekyll (3.1.1, 3.1.0)
jekyll-docs (3.1.1)
jekyll-import (0.10.0)
jekyll-sass-converter (1.4.0)
jekyll-watch (1.3.1)
[...]

$ jekyll docs
You must install the 'jekyll-docs' gem to use the 'jekyll docs' command.

When the latest version of Jekyll being 3.4.0 (as of 31 Jan 2017), it seems the jekyll-docs gem on Rubygems.org doesn't work as the latest version of the jekyll-docs gem is 3.3.1.

Any news on when is this is launching or what I can do to get this up to date?

The gems works like a charm, doing what it says. But there are still some Jekyll users that run it on Windows, and re-building the site every time we do jekyll docs sometimes takes a long time to just build, and disk space of course.

So the idea is: build the site on bundle exec rake build, then change the code to just serve it with the default Jekyll serve command. Maybe it needs to get a lot of dependencies (jekyll-feed and others used by the docs site), but many will be thankful.

When I run the jekyll docs cmd I still an error. Am I missing anything?
btw I love that you guys have this feature, since I do work offline quite a bit and enjoy having the docs, so thank you for supporting this option even though it seems it may have become a sore point.

• I am outside a project directory with no gemfile as per issue #14.
• I tried applying all fixes not pertaining to a gemfile I could see on issue #5, see below.
• Tried installing pygments.rb as per issue #12 with no change.

$uname -svrio
Linux 4.4.0-31-generic #50 Ubuntu x86_64 GNU/Linux (omitted version datetime)
$ ls -a
. .. testblog
$ gem list | grep jekyll
jekyll (3.3.1, 3.3.0)
jekyll-docs (3.3.0)
jekyll-feed (0.8.0)
jekyll-sass-converter (1.5.0)
jekyll-watch (1.5.0)
$ jekyll docs
You must install the 'jekyll-docs' gem to use the 'jekyll docs' command.
$ jekyll docs -v
docs
$ jekyll docs -h 
(shows usage documentation, omitted for brevity, btw there are two lines for -t, --trace)
$ jekyll docs --verbose --trace
jekyll 3.3.1 | Error: Whoops, we can't understand your command.
jekyll 3.3.1 | Error: invalid option: --verbose
jekyll 3.3.1 | Error: Run your command again with the --help switch to see available options.
$ jekyll docs --trace
You must install the 'jekyll-docs' gem to use the 'jekyll docs' command.
$ irb
irb> require 'jekyll-docs'
=> true

$ jekyll docs --help
jekyll docs -- Start a local server for the Jekyll documentation

Usage:

  jekyll docs [options]

Options:
 -P [PORT], --port [PORT]  Port to listen on.
        -h, --help         Show this message
        -v, --version      Print the name and version
        -t, --trace        Show the full backtrace when an error occurs
        -s, --source [DIR]  Source directory (defaults to ./)
        -d, --destination [DIR]  Destination directory (defaults to ./_site)
            --safe         Safe mode (defaults to false)
        -p, --plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]  Plugins directory (defaults to ./_plugins)
            --layouts DIR  Layouts directory (defaults to ./_layouts)
            --profile      Generate a Liquid rendering profile
        -h, --help         Show this message
        -v, --version      Print the name and version
        -t, --trace        Show the full backtrace when an error occurs

$ jekyll docs -v
docs

Edit: looks like this option isn't implemented.

I've installed the "docs" bundle following the instructions on the README at https://github.com/jekyll/jekyll-docs by adding gem 'jekyll-docs' to the Gemfile of my GitHub pages repo and running Bundle

Running `Bundle show' points to Jekyll-docs being installed:

jjarava$ bundle show jekyll-docs
/Library/Ruby/Gems/2.0.0/gems/jekyll-docs-1.0.0.pre.rc1

But trying to run either bundle exec jekyll docs or jekyll docs gives an error:

jjarava$ bundle exec jekyll docs
Configuration file: none
            Source: /Library/Ruby/Gems/2.0.0/gems/jekyll-2.4.0/site
       Destination: /Library/Ruby/Gems/2.0.0/gems/jekyll-2.4.0/site/_site
      Generating...
jekyll 2.4.0 | Error:  No such file or directory - /Library/Ruby/Gems/2.0.0/gems/jekyll-2.4.0/site/

Following the installation instructions produces the following errors:

$ sudo gem install jekyll-docs -v 3.6.2
[sudo] password for <user>: 
Fetching: jekyll-docs-3.6.2.gem (100%)
Successfully installed jekyll-docs-3.6.2
Parsing documentation for jekyll-docs-3.6.2
Installing ri documentation for jekyll-docs-3.6.2
Done installing documentation for jekyll-docs after 1 seconds
1 gem installed
$ jekyll _3.6.2_ docs
You must install the 'jekyll-docs' gem version = 3.6.2 to use the 'jekyll docs' command.
$ jekyll docs
You must install the 'jekyll-docs' gem version = 3.6.2 to use the 'jekyll docs' command.
$ gem list docs

*** LOCAL GEMS ***

jekyll-docs (3.6.2)

I see that there are files successfully installed to /var/lib/gems/2.3.0/doc/jekyll-docs-3.6.2, but I can't access them with jekyll docs or jekyll _3.6.2_ docs.

There have been lots of other issues with this similar problem (#5, #12, #14, #15, #20), but as they're closed and regarding older versions I'm opening a new issue.

My system:

$ gem --version
2.7.3
$ ruby --version
ruby 2.3.1p112 (2016-04-26) [x86_64-linux-gnu]
$ jekyll --version
jekyll 3.6.2
$ uname -sr
Linux 4.4.0-101-generic
$ lsb_release -dc
Description:	Ubuntu 16.04.3 LTS
Codename:	xenial

and strangely

$ jekyll docs --version
docs 

Thoughts? Thanks!

There is a page in the docs about Markdown options, but no hint how to set them.

I googled it and found this post where it is explained:
https://scottw.com/setting-kramdown-options-for-jekyll

I think it would be helpful to integrate that information here :)

jekyll docs -h tells to use -P to use a non-default port but this fails with a bogus error message.

Transcript:

$ jekyll docs -P 3000
Configuration file: none
jekyll 3.4.3 | Error:  no implicit conversion of true into String

I successfully installed jekyll-docs, but I get this error message

~ $ jekyll docs  
You must install the 'jekyll-docs' gem to use the 'jekyll docs' command.

I have installed
jekyll-docs (3.1.6)
jekyll (3.1.6)

Similar issues have been raised for earlier versions: #5

I don't know if this should be a jekyll or jekyll docs issue but this is something that I find a little annoying. A few months back it made me give up on this gem but today I found a way around.

If you run jekyll docs inside a jekyll project it fails and tell you to install the gem. To get this to work, you have to run the command outside of a jekyll project.

Maybe this is mentioned somewhere but it would be nice if it mentioned on the read me.