jekyll-docs 2.5.3 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c760698c76c16814fa17a1e2bb049a95d898e1ef
-  data.tar.gz: af335abd2223f8ffd611168cb7f0b5399f994c73
+  metadata.gz: 8f516971da8b5173528c10ffc951a3ab53986576
+  data.tar.gz: 2577f66a33d3402bdd832c1d8961fe725a22ec18
 SHA512:
-  metadata.gz: e9760609b4b898f00f9cd435f557814cc29da4d70b0396cf0974028d059dc1cbd88297f8191352f72a399b467e87717e731ba779bdfe1c497eee8b2a9e19c870
-  data.tar.gz: 122efe7a48ad9e1956f78ff60204da95cebf56114996831c2845d0479882e7831f404b691acf961abb6c14f4de2b64b6d115fe9406e6a0dde39554affdf5728e
+  metadata.gz: 3a4d59816c59bb0ab3f9d6e8af7cd576de38d55aa1af058049d3b8f9cc0cf5f1a30194983a0eb3fbb22af740d13948a9460149d7350e5fc417a59fffd5d52177
+  data.tar.gz: b73b89b5ff1589ccc268c5dc3780c60dca889a74e55262173b05630cc1d83bdda7688052acd895305859fcb0ce6ac598c0c6260c49aa4f5da4482124de07f2e5

data/lib/jekyll-docs.rb

@@ -1,7 +1,37 @@
-require 'jekyll-docs/version'
-require 'jekyll/commands/docs'
+require 'rubygems'
+require 'jekyll'
+require 'tmpdir'
 
-module Jekyll
-  module Docs
+module JekyllDocs
+  class DocsCommand < Jekyll::Command
+    class << self
+      def init_with_program(prog)
+        prog.command(:docs) do |cmd|
+          cmd.description "Start a local server for the Jekyll documentation"
+          cmd.syntax "docs [options]"
+          cmd.alias :d
+
+          cmd.option "port", "-P", "--port", "Port to listen on."
+
+          cmd.action do |_, opts|
+            JekyllDocs::DocsCommand.process(opts)
+          end
+        end
+      end
+
+      def process(opts)
+        Dir.mktmpdir do |dest_dir|
+          options = opts.merge({
+            "serving"     => true,
+            "watch"       => false,
+            "config"      => File.expand_path("../../site/_config.yml", __FILE__),
+            "source"      => File.expand_path("../../site", __FILE__),
+            "destination" => dest_dir
+          })
+          Jekyll::Commands::Build.process(options)
+          Jekyll::Commands::Serve.process(options)
+        end
+      end
+    end
   end
 end

data/site/CNAME

@@ -0,0 +1 @@
+jekyllrb.com

data/site/README.md

@@ -0,0 +1,16 @@
+# Jekyll docs site
+
+This directory contains the code for the Jekyll docs site, [jekyllrb.com](http://jekyllrb.com/).
+
+## Contributing
+
+For information about contributing, see the [Contributing page](http://jekyllrb.com/docs/contributing/).
+
+## Running locally
+
+You can preview your contributions before opening a pull request by running from within the directory:
+
+1. `bundle install`
+2. `bundle exec rake site:preview`
+
+It's just a jekyll site, afterall! :wink:

data/site/_config.yml

@@ -0,0 +1,21 @@
+markdown: kramdown
+highlighter: pygments
+permalink: /news/:year/:month/:day/:title/
+excerpt_separator: ""
+
+gauges_id: 503c5af6613f5d0f19000027
+google_analytics_id: UA-50755011-1
+
+repository: https://github.com/jekyll/jekyll
+help_url: https://github.com/jekyll/jekyll-help
+
+collections:
+  docs:
+    output: true
+
+name: Jekyll • Simple, blog-aware, static sites
+description: Transform your plain text into static websites and blogs
+url: http://jekyllrb.com
+
+gems:
+  - jekyll-feed

data/site/_data/docs.yml

@@ -0,0 +1,47 @@
+- title: Getting Started
+  docs:
+  - home
+  - quickstart
+  - installation
+  - usage
+  - structure
+  - configuration
+
+- title: Your Content
+  docs:
+  - frontmatter
+  - posts
+  - drafts
+  - pages
+  - static-files
+  - variables
+  - collections
+  - datafiles
+  - assets
+  - migrations
+
+- title: Customization
+  docs:
+  - templates
+  - permalinks
+  - pagination
+  - plugins
+  - extras
+
+- title: Deployment
+  docs:
+  - github-pages
+  - deployment-methods
+  - continuous-integration
+
+- title: Miscellaneous
+  docs:
+  - troubleshooting
+  - sites
+  - resources
+  - upgrading
+
+- title: Meta
+  docs:
+  - contributing
+  - history

data/site/_docs/assets.md

@@ -0,0 +1,93 @@
+---
+layout: docs
+title: Assets
+permalink: /docs/assets/
+---
+
+Jekyll provides built-in support for Sass and can work with CoffeeScript via 
+a Ruby gem. In order to use them, you must first create a file with the 
+proper extension name (one of `.sass`, `.scss`, or `.coffee`) and start the 
+file with two lines of triple dashes, like this:
+
+{% highlight sass %}
+---
+---
+
+// start content
+.my-definition
+  font-size: 1.2em
+{% endhighlight %}
+
+Jekyll treats these files the same as a regular page, in that the output file
+will be placed in the same directory that it came from. For instance, if you
+have a file named `css/styles.scss` in your site's source folder, Jekyll
+will process it and put it in your site's destination folder under
+`css/styles.css`.
+
+<div class="note info">
+  <h5>Jekyll processes all Liquid filters and tags in asset files</h5>
+  <p>If you are using <a href="http://mustache.github.io">Mustache</a>
+     or another JavaScript templating language that conflicts with
+     the <a href="/docs/templates/">Liquid template syntax</a>, you
+     will need to place <code>{&#37; raw &#37;}</code> and
+     <code>{&#37; endraw &#37;}</code> tags around your code.</p>
+</div>
+
+## Sass/SCSS
+
+Jekyll allows you to customize your Sass conversion in certain ways.
+
+Place all your partials in your `sass_dir`, which defaults to
+`<source>/_sass`. Place your main SCSS or Sass files in the place you want
+them to be in the output file, such as `<source>/css`. For an example, take
+a look at [this example site using Sass support in Jekyll][example-sass].
+
+If you are using Sass `@import` statements, you'll need to ensure that your
+`sass_dir` is set to the base directory that contains your Sass files. You
+can do that thusly:
+
+{% highlight yaml %}
+sass:
+    sass_dir: _sass
+{% endhighlight %}
+
+The Sass converter will default the `sass_dir` configuration option to
+`_sass`.
+
+[example-sass]: https://github.com/jekyll/jekyll-sass-converter/tree/master/example
+
+<div class="note info">
+  <h5>The <code>sass_dir</code> is only used by Sass</h5>
+  <p>
+
+    Note that the <code>sass_dir</code> becomes the load path for Sass imports,
+    nothing more. This means that Jekyll does not know about these files
+    directly, so any files here should not contain the YAML Front Matter as
+    described above nor will they be transformed as described above. This
+    folder should only contain imports.
+
+  </p>
+</div>
+
+You may also specify the output style with the `style` option in your
+`_config.yml` file:
+
+{% highlight yaml %}
+sass:
+    style: compressed
+{% endhighlight %}
+
+These are passed to Sass, so any output style options Sass supports are valid
+here, too.
+
+
+## Coffeescript
+
+To enable Coffeescript in Jekyll 3.0 and up you must 
+ * Install the `jekyll-coffeescript` gem
+ * Ensure that your `_config.yml` is up-to-date and includes the following
+
+{% highlight yaml %}
+gems:
+ - jekyll-coffeescript
+{% endhighlight %}

data/site/_docs/collections.md

@@ -0,0 +1,380 @@
+---
+layout: docs
+title: Collections
+permalink: /docs/collections/
+---
+
+<div class="note warning">
+  <h5>Collections support is unstable and may change</h5>
+  <p>
+    This is an experimental feature and the API may change until the feature stabilizes.
+  </p>
+</div>
+
+Not everything is a post or a page. Maybe you want to document the various
+methods in your open source project, members of a team, or talks at a
+conference. Collections allow you to define a new type of document that behave
+like Pages or Posts do normally, but also have their own unique properties and
+namespace.
+
+## Using Collections
+
+### Step 1: Tell Jekyll to read in your collection
+
+Add the following to your site's `_config.yml` file, replacing `my_collection`
+with the name of your collection:
+
+{% highlight yaml %}
+collections:
+- my_collection
+{% endhighlight %}
+
+You can optionally specify metadata for your collection in the configuration:
+
+{% highlight yaml %}
+collections:
+  my_collection:
+    foo: bar
+{% endhighlight %}
+
+Default attributes can also be set for a collection:
+
+{% highlight yaml %}
+defaults:
+  - scope:
+      path: ""
+      type: my_collection
+    values:
+      layout: page
+{% endhighlight %}
+
+### Step 2: Add your content
+
+Create a corresponding folder (e.g. `<source>/_my_collection`) and add
+documents. YAML Front Matter is read in as data if it exists, and everything
+after it is stuck in the Document's `content` attribute. If no YAML Front
+Matter is provided, Jekyll will not generate the file in your collection.
+
+<div class="note info">
+  <h5>Be sure to name your directories correctly</h5>
+  <p>
+The folder must be named identically to the collection you defined in
+your <code>_config.yml</code> file, with the addition of the preceding <code>_</code> character.
+  </p>
+</div>
+
+### Step 3: Optionally render your collection's documents into independent files
+
+If you'd like Jekyll to create a public-facing, rendered version of each
+document in your collection, set the `output` key to `true` in your collection
+metadata in your `_config.yml`:
+
+{% highlight yaml %}
+collections:
+  my_collection:
+    output: true
+{% endhighlight %}
+
+This will produce a file for each document in the collection.
+For example, if you have `_my_collection/some_subdir/some_doc.md`,
+it will be rendered using Liquid and the Markdown converter of your
+choice and written out to `<dest>/my_collection/some_subdir/some_doc.html`.
+
+As for posts with [Permalinks](../permalinks/), the document
+URL can be customized by setting `permalink` metadata for the collection:
+
+{% highlight yaml %}
+collections:
+  my_collection:
+    output: true
+    permalink: /awesome/:path/
+{% endhighlight %}
+
+For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be
+written out to `<dest>/awesome/some_subdir/some_doc/index.html`.
+
+<div class="note info">
+  <h5>Don't forget to add YAML for processing</h5>
+  <p>
+  Files in collections that do not have front matter are treated as
+  <a href="/docs/static-files">static files</a> and simply copied to their
+  output location without processing.
+  </p>
+</div>
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>collection</code></p>
+      </td>
+      <td>
+        <p>Label of the containing collection.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>path</code></p>
+      </td>
+      <td>
+        <p>Path to the document relative to the collection's directory.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>name</code></p>
+      </td>
+      <td>
+        <p>The document's base filename, with every sequence of spaces
+        and non-alphanumeric characters replaced by a hyphen.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>title</code></p>
+      </td>
+      <td>
+        <p>The document's lowercase title (as defined in its <a href="/docs/frontmatter/">front matter</a>), with every sequence of spaces and non-alphanumeric characters replaced by a hyphen. If the document does not define a title in its <a href="/docs/frontmatter/">front matter</a>, this is equivalent to <code>name</code>.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>output_ext</code></p>
+      </td>
+      <td>
+        <p>Extension of the output file.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+## Liquid Attributes
+
+### Collections
+
+Each collection is accessible via the `site` Liquid variable. For example, if
+you want to access the `albums` collection found in `_albums`, you'd use
+`site.albums`. Each collection is itself an array of documents
+(e.g. `site.albums` is an array of documents, much like `site.pages` and
+`site.posts`). See below for how to access attributes of those documents.
+
+The collections are also available under `site.collections`, with the metadata
+you specified in your `_config.yml` (if present) and the following information:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>label</code></p>
+      </td>
+      <td>
+        <p>
+          The name of your collection, e.g. <code>my_collection</code>.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>docs</code></p>
+      </td>
+      <td>
+        <p>
+          An array of <a href="#documents">documents</a>.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>files</code></p>
+      </td>
+      <td>
+        <p>
+          An array of static files in the collection.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>relative_directory</code></p>
+      </td>
+      <td>
+        <p>
+          The path to the collection's source directory, relative to the site
+          source.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>directory</code></p>
+      </td>
+      <td>
+        <p>
+          The full path to the collections's source directory.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>output</code></p>
+      </td>
+      <td>
+        <p>
+          Whether the collection's documents will be output as individual
+          files.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+
+### Documents
+
+In addition to any YAML Front Matter provided in the document's corresponding
+file, each document has the following attributes:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>content</code></p>
+      </td>
+      <td>
+        <p>
+          The (unrendered) content of the document. If no YAML Front Matter is
+          provided, Jekyll will not generate the file in your collection. If
+          YAML Front Matter is used, then this is all the contents of the file
+          after the terminating
+          `---` of the front matter.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>output</code></p>
+      </td>
+      <td>
+        <p>
+          The rendered output of the document, based on the
+          <code>content</code>.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>path</code></p>
+      </td>
+      <td>
+        <p>
+          The full path to the document's source file.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>relative_path</code></p>
+      </td>
+      <td>
+        <p>
+          The path to the document's source file relative to the site source.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>url</code></p>
+      </td>
+      <td>
+        <p>
+          The URL of the rendered collection. The file is only written to the
+          destination when the name of the collection to which it belongs is
+          included in the <code>render</code> key in the site's configuration
+          file.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>collection</code></p>
+      </td>
+      <td>
+        <p>
+          The name of the document's collection.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+## Accessing Collection Attributes
+
+Attributes from the YAML front matter can be accessed as data anywhere in the
+site. Using the above example for configuring a collection as `site.albums`,
+one might have front matter in an individual file structured as follows (which
+must use a supported markup format, and cannot be saved with a `.yaml`
+extension):
+
+{% highlight yaml %}
+title: "Josquin: Missa De beata virgine and Missa Ave maris stella"
+artist: "The Tallis Scholars"
+director: "Peter Phillips"
+works:
+  - title: "Missa De beata virgine"
+    composer: "Josquin des Prez"
+    tracks:
+      - title: "Kyrie"
+        duration: "4:25"
+      - title: "Gloria"
+        duration: "9:53"
+      - title: "Credo"
+        duration: "9:09"
+      - title: "Sanctus & Benedictus"
+        duration: "7:47"
+      - title: "Agnus Dei I, II & III"
+        duration: "6:49"
+{% endhighlight %}
+
+Every album in the collection could be listed on a single page with a template:
+
+{% highlight html %}
+{% raw %}
+{% for album in site.albums %}
+  <h2>{{ album.title }}</h2>
+  <p>Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %}</p>
+  {% for work in album.works %}
+    <h3>{{ work.title }}</h3>
+    <p>Composed by {{ work.composer }}</p>
+    <ul>
+    {% for track in work.tracks %}
+      <li>{{ track.title }} ({{ track.duration }})</li>
+    {% endfor %}
+    </ul>
+  {% endfor %}
+{% endfor %}
+{% endraw %}
+{% endhighlight %}