Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation improvements - Bundler, front matter #24

Merged
merged 5 commits into from
Jan 7, 2015
Merged

Documentation improvements - Bundler, front matter #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
22dcae1
doc fix
Jan 6, 2015
89b43c1
docFix
Jan 6, 2015
9db0195
docFix
Jan 6, 2015
9d0e6ac
Resolves #25 fix for front matter description
eshepelyuk Jan 7, 2015
e3b64ea
Resolves #25 link to jekyll site about fron matter
eshepelyuk Jan 7, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,5 @@
/*.gem
/pkg/
/Gemfile.lock
.idea
*.iml
52 changes: 35 additions & 17 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,39 +21,52 @@ You can install the gem using:

$ gem install asciidoctor

If you are using Bundler to manage the dependencies in your Jekyll project, then add the Asciidoctor gem instead to your `Gemfile` (below the Jekyll gem, named jekyll):
If you are using Bundler to manage the dependencies in your Jekyll project, then add the Asciidoctor gem to your `Gemfile` (below the Jekyll gem, named jekyll):

[source,ruby]
----
source 'https://rubygems.org'

gem 'jekyll'
gem 'asciidoctor'
----

Then, run the Bundler install command, `bundle`:

$ bundle

=== Using a release

First, install the Jekyll AsciiDoc gem (named `jekyll-asciidoc`):
Then, run the Bundler install command

$ gem install jekyll-asciidoc`
$ bundle install
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically the "install" part is not required. "install" is the default action for the bundle command.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Absolutely agree, but in this case my intention was to make command line to be more 'self-explanatory', for instance for people not familiar with Bundler.
Although, I can delete install if you prefer.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please choose what you feel is best. I was just pointing it out. It was only recently I learned this trick.


If you are using Bundler to manage the dependencies, add the `jekyll-asciidoc` gem to your `Gemfile`:
=== Installing a released version of the plugin

Using Bundler::
+
Add `jekyll-asciidoc` plugin gem to your `Gemfile`
+
[source,ruby]
gem 'jekyll-asciidoc'

----
group :jekyll_plugins do
gem "jekyll-asciidoc"
end
----
+
Then, run the Bundler command to install it:

$ bundle

Finally, add the `jekyll-asciidoc` gem to the list of gems for Jekyll to load in your site's `_config.yml` file:
$ bundle install

Without Bundler::
+
If you are not using Bundler for managing Jekyll then install gems manually
+
$ gem install jekyll-asciidoc
+
And then, add `jekyll-asciidoc` gem to the list of gems for Jekyll to load in your site's `_config.yml` file:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the part about adding jekyll-asciidoc to the _config.yml file should be part of the previous list because it applies to both cases. Correct?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really, when you're using Bundler it's enough to add plugin into corresponding group in Gemfile.
As described at Installing a plugin section of Jekyll docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah. I did not realize that. I'm not sure I agree that's the best way for Jekyll to handle it, but I now see it is the recommended way.

+
[source,yaml]
----
gems:
- jekyll-asciidoc
----

=== Using the development version
=== Installing development version of the plugin

To install the development version of this plugin, copy `lib/asciidoc_plugin.rb` to the `_plugins` directory in the root of your site source.

Expand Down Expand Up @@ -81,7 +94,7 @@ puts "Hello, World!"
----
....

IMPORTANT: The AsciiDoc file must have a Markdown-style front matter header or else it won't be recognized as a page.
IMPORTANT: The AsciiDoc file must have a http://jekyllrb.com/docs/frontmatter/[YAML front matter] header or else it won't be recognized as a page.
You can use an empty front matter header, as shown above, or you can define all your document metadata (e.g., document title) in the front matter instead of AsciiDoc attributes.

You can now build your site using:
Expand All @@ -91,6 +104,11 @@ You can now build your site using:
and preview it using:

$ jekyll serve

If you are using Bundler then use following commands to do the same

$ bundle exec jekyll build
$ bundle exec jekyll serve

IMPORTANT: If you use the `--safe` option, the AsciiDoc plugin will not be activated.
The `--safe` flag disables third-party plugins such as this one.
Expand Down