Skip to content

Support for AsciiDoc#102

Merged
Phlow merged 11 commits intoPhlow:gh-pagesfrom
nerk:gh-pages
Aug 12, 2016
Merged

Support for AsciiDoc#102
Phlow merged 11 commits intoPhlow:gh-pagesfrom
nerk:gh-pages

Conversation

@nerk
Copy link
Contributor

@nerk nerk commented Jul 31, 2016

Provides AsciiDoc support in addition to Markdown. 'bundle install' installs all necessary jekyll plugins and gems.

Create posts or pages with AsciiDoc markup with suffixes '.adoc', '.asciidoc', or '.ad'.

For more details see http://asciidoctor.org and https://github.com/asciidoctor/jekyll-asciidoc

@nerk
Copy link
Contributor Author

nerk commented Aug 1, 2016

But to use AsciiDoc, you need a plugin, right? It's not compatible with GitHub Pages?!?

Yes sorry, seems that Github Pages does not whitelist the plugin yet. I did not consider this, because I just generated everything locally.

Maybe we could comment the jekyll-asciidoc plugin and the configuration in _config.yml and Gemfile. People who want to use AsciiDoc can just uncomment it and generate the site 'offline'?

However, if you'd rather not merge this at all because of this, that's fine with me.

@Phlow
Copy link
Owner

Phlow commented Aug 12, 2016

It took some time. OK. I pull it now.

@Phlow Phlow merged commit dd48bd2 into Phlow:gh-pages Aug 12, 2016
@TWiStErRob
Copy link
Contributor

TWiStErRob commented Aug 12, 2016

Code duplication and branching for <style> is unnecessary. You could've simply put the following into styles_feeling_responsive.scss:

{% if site.asciidoctor %}
@import "10_asciidoc.scss";
{% endif %}

@Phlow
Copy link
Owner

Phlow commented Aug 12, 2016

Does ruby work in .scss-files?

And you're right, it should be optional.

@TWiStErRob
Copy link
Contributor

No, Ruby doesn't, but it's a template so it'll go through a Liquid pass, notice that it has frontmatter!

@Phlow
Copy link
Owner

Phlow commented Aug 12, 2016

You're right! Great, I didn't know. I will add it immediately. Thankyou for taking care.

@TWiStErRob
Copy link
Contributor

TWiStErRob commented Aug 12, 2016

Here's a live example: http://www.twisterrob.net/blog/tags/

I'm using this technique for generating some SCSS based on yml files in _data: site-data_colors.scss is generated based on for example tags.yml included from styles_feeling_responsive.scss. Include is a Liquid tag, as contents of the other file was written there, not @import which is SCSS level.

@Phlow
Copy link
Owner

Phlow commented Aug 12, 2016

Uffz. Quite complex. But the possibility is great to make use of it in _config.yml

So in the future I could offer a switch to use different color schemes based on settings in _config.yml

I will check this out for my other theme Simplicity – there i have already different color schemes, but they are only available, if you hack the .scss-files

@nerk
Copy link
Contributor Author

nerk commented Aug 12, 2016

Great, much better! I did not know that it would be preprocessed through Liquid.

@Phlow
Copy link
Owner

Phlow commented Aug 12, 2016

I added a switch and some information for people who don't know about asciidoctor. Hope you like it :)

@TWiStErRob
Copy link
Contributor

@nerk just curious: why does it need so much custom styling?

@nerk
Copy link
Contributor Author

nerk commented Aug 12, 2016

It supports a lot more specialized elements than Markdown, for example

  • Admonitions and Admonition blocks
  • Open Blocks
  • Listing (with and without syntax highlighting)
  • Example blocks
  • Sidebars
  • more list styles
  • etc.

Furthermore, the generated HTML is sometimes a bit peculiar (for historical reasons) and needs a bit of special attention by style sheets.

If you are interested, here is a good overview on what is possible:

http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

@TWiStErRob
Copy link
Contributor

Thanks.

@mojavelinux
Copy link

Just for fun I converted part of the changelog so you could see how I'd look in AsciiDoc. Notice that AsciiDoc actually has support for a document header, drastically reducing the noise of the front matter.

= Change is good!
:page-layout: page
:page-meta_title: Feeling Responsive Theme Changelog
:page-subheadline: {page-meta_title}
:page-teaser: History and changelog of Feeling Responsive Theme
:page-header: { image_fullwidth: header_unsplash_9.jpg }
:page-permalink: /changelog/
:page-liquid:

2015-11-10 // Version 1.91::
I added a nasty hack to highlight the homepage in the topbar navigation.
To do it, you have to add `homepage: true` to your homepage.
The pages _404_ and _search_ are now excluded from the sitemap.

2015-10-29 // Version 1.9::
I needed a call for action button on the frontpage to get your awareness for the new and fresh https://tinyletter.com/feeling-responsive[_Feeling Responsive_-Newsletter] which informs you about new features.
Now you can use it, too.
Just have a look into _pages/pages-root-folder/index.md_ to delete or use it.
Uh, there were some images missing and the video-template didn't show up correct.
I use now `{% raw %}{{ layout.format }}{% endraw %}` to inject the class of a layout in `default.html` into `<body>` to make it work.

2015-10-27 // Version 1.8::
_Feeling Responsive_ works smoothly with http://jekyllrb.com/news/2015/10/26/jekyll-3-0-released/[Jekyll 3.0].
I added a Gemfile with the pagination gem _jekyll-paginate_ so that paginate works.
And now there is also a https://github.com/Phlow/feeling-responsive/tree/bare-bones-version[bones-version] available to get a clean project started right from the beginning.

2015-10-18 // Version 1.7::
Now with audio- and video-player {{ site.url }}/design/mediaelement_js/[mediaelement.js].
Added new gallery include.
Changed names again... Sorry.

2015-08-07 // Version 1.5::
Simplified includes syntax.
The `.html`-ending is not needed anymore.
Makes it simpler to read, write and use.

@ghost
Copy link

ghost commented May 21, 2017

@mojavelinux that's cool. any gotchas you see for creating links or dropping in structured markup? Also curious about array/list representations.

You may also be interested in http://keepachangelog.com/en/0.3.0/

@mojavelinux
Copy link

Also curious about array/list representations.

All attributes that start with page- (which is a configurable prefix) get parsed as YAML values. So it technically matches what Jekyll front matter does. After that, it's kind of up to the hand-off as to what happens with that value.

any gotchas you see for creating links or dropping in structured markup?

AsciiDoc allows you to "passthrough" content using the inline passthrough macro, so it's pretty easy to pass raw HTML if necessary. But you can also just put inline AsciiDoc in there and then parse it down the line somewhere. It really depends on how it's used.

The plugin provides an AsciiDoc filter that you can use to convert inline content in your liquid template.

@mojavelinux
Copy link

There's a ton of documentation on all this in the plugin README. https://github.com/asciidoctor/jekyll-asciidoc#creating-pages (Though, as always, more is needed)

@ghost
Copy link

ghost commented May 21, 2017

zang

rollingrock pushed a commit to rollingrock/joelucky that referenced this pull request Aug 31, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants