jekyll / jekyll-docs Goto Github PK

View Code? Open in Web Editor NEW

37.0 10.0 16.0 36 KB

Offline usage documentation for Jekyll. Requires Jekyll 3 and above.

Home Page: https://rubygems.org/gems/jekyll-docs

License: MIT License

Ruby 92.70% Shell 7.30%

jekyll offline documentation

jekyll-docs's Introduction

jekyll-docs

This gem is how we ship the docs on jekyllrb.com to users who want local, offline access to the docs.

Installing

Replace <JEKYLL_VERSION> with the version of Jekyll you wish to use (e.g. 3.8.1) and run:

gem install jekyll-docs -v <JEKYLL_VERSION>

Or, add it to your Gemfile:

gem 'jekyll-docs', '<JEKYLL_VERSION>'

Then, run bundle install.

Usage

⚠️ You can not generate the documentation website in an existing Jekyll source folder.

Once installed, you have to ensure you're using the same version of Jekyll and jekyll-docs:

$ jekyll _<JEKYLL_VERSION>_ docs
$ # If you want Jekyll v3.8.1, you have to run:
$ jekyll _3.8.1_ docs

😄

Building

$ export JEKYLL_VERSION=3.8.1 # (or whatever)
$ bundle install
$ bundle exec rake build

Now you have it in pkg/jekyll-docs-3.8.1.gem.

Releasing

Ensure the tag for the version is available on the jekyll/jekyll repo in the form of vVERSION, e.g. v3.8.1.

$ export JEKYLL_VERSION=3.8.1
$ script/bootstrap
$ bundle exec rake release

Made a mistake? You can release another version of jekyll-docs by running the following:

$ export JEKYLL_VERSION=3.8.1
$ export JEKYLL_DOCS_VERSION=${JEKYLL_VERSION}.1 # Increment .1 to .2 if this is your second fix, etc.
$ script/bootstrap
$ bundle exec rake release

jekyll-docs's People

Contributors

Stargazers

Watchers

Forkers

karthikchandrasekar moughamir animeshbaranawal kleopatra999 codecommunity bih funkmyster meghanhorton dalavancloud a2nr changsongyang seanpm2001

jekyll-docs's Issues

Unable to run command "jekyll docs" for version 3.1.6

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

IDEA: site build then package

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.

jekyll-docs fails to install

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!

Jekyll docs --version doesn't display current version

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

Can't launch the "docs" site

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/

docs is not offline

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>

Release 3.1.4 docs

Run jekyll-docs is resulting a error message

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:

Support Ruby > 2.1

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?

Release 3.1.6 docs

jekyll-docs error message after installing gem

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.

jekyll docs -P <port_number> fails

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

Create docs for 3.4.0

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?

Unable to run command "jekyll docs" for version 3.3.1

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

Release 3.1.5 docs

Jekyll docs command fails in jekyll project

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.

Release 3.1.3 docs

Host versioned docs online

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

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

I'm involved in the development of the Just the Docs theme, and we'd like to make our theme docs versioned, as well as supporting versioning for our users. ↩

Explain how to set kramdown options

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