Comments (16)
Having dabbled with RevealJS, I'd definitely like to work on/contribute to this endeavor.
from asciidoctor-backends.
Cool, I implemented the deck.js backend so if you have any question feel free to ask me here or by using http://discuss.asciidoctor.org/
from asciidoctor-backends.
@jordanmccullough That's great to hear! We've got a reveal.js pro in the house! Woot!
Although you probably don't need any hints, I know @paulrayner has played around with a reveal.js backend for Asciidoctor for one (or more) of his presentations. However, he was extending the built-in classes instead of using Tilt. Custom backends should be done using Tilt because the built-in classes should be treated as private.
My one word of advice is to aim for the simplest possible syntax (roles, options, etc) that will work. @jordanmccullough you probably don't need any convincing on that coming from Markdown. Hopefully you'll find the AsciiDoc syntax is a good fit for achieving the type of hierarchical organization of slides that you have in HydeSlides.
Happy hacking!
from asciidoctor-backends.
Writing a revealjs backend right now. Using tilt and haml. Never really used haml/titlt/revealjs and have to learn the structure asciidoctor calls the haml files.
Created a subdirectory asciidoctor-backends/haml/revealjs and started with document.html.haml. Is that the right direction?
from asciidoctor-backends.
@buuhsmead Excellent!
I recommend starting with either haml or tilt (I see you chose haml, which is fine). It's easy to then port it to slim. Using multiple engines in the backend doesn't really benefit users, but it gives people interested in hacking on it the raw material if they prefer to use one engine over another. To be honest, I'm still debating with myself what the best approach is.
You have the right idea to get started:
- Create the directory
<engine>/revealjs
in the asciidoctor-backends repository, where<engine>
is the template engine (e.g., haml, slim or erb) - Start hacking on
document.html.<engine>
, moving on tosection.html.<engine>
, then likelyblock_paragraph.html.<engine>
,block_ulist.html.<engine>
and so forth
I'll give a brief overview of the object model that is available for each template (hopefully so it makes its way into some official documentation soon).
Each template represents one type of document node, similar to an XML DOM node. There are three types of nodes:
- document (which is a type of block)
- block
- inline
The first template to be invoked is document.html.. When the content variable (technically a method) of a node is referenced, the rest of the document is rendered by walking the document recursively and rendering each node.
You can think of the template as a single method call on the node object. Within the template, you have access to all the instance variables and instance methods of the node, just as you would inside a method call.
For example, the following line invokes the content()
method on the node:
=content
Each node holds the following common information:
- id
- attributes hash
- context (corresponds to the template name)
- reference to parent node and current document
Block nodes hold the following additional information:
- title
- caption
- style (the block qualifier)
- reference to nested content *
* In a list block, the content is a collection of the list items.
Inline nodes hold the following additional information:
- text
- type
- target
The following table shows some of the instance variables and instance methods you'll use in a template:
Name | Example(s) | Description |
---|---|---|
content | content | Renders the children of this node (if any) and returns the result. |
id | @id | The id assigned to the block or nil of no id is assigned. |
document | @document | A reference to the current document (and all of its nodes). |
attr(name, default = nil) | attr('language') attr('toc-class', 'toc') @document.attr('icons', 'font') |
Retrieves the value of the specified attribute in the attributes hash, using the name as a key. If the name is written as a symbol, it will be automatically converted to a string before lookup. |
attr?(name, match = nil) | attr?('icons') attr?('toc-placement', 'auto') |
Checks whether the specified attribute exists in the attribute hash, using the name as the key. If the name is written as a symbol, it will be automatically converted to a string before lookup. If a match is provided, additionally checks whether the attribute value matches the specified value. |
style | @Style | Retrieves the style (qualifier) for a block. If the block does not have a style, nil is returned. |
role | role | A convenience method that returns the role attribute for the block, or nil if the block does not have a role. |
role? | role? | A convenience method to check whether the block has the role attribute. |
option?(name) | option?('loop') | A convenience method to check whether the specified option attribute (e.g., loop-option) is present. |
title | title | Retrieves the title of the block with normal substitutions (escape XML, render links, etc) applied. |
title? | title? | Checks whether a title has been assigned to this block. This method does not have side effects (e.g., checks for existence only, does not apply substitutions) |
image_uri(path) | image_uri(attr 'target') | Converts the path into an image uri (reference or embedded data) to be used in an HTML img tag. Applies security restrictions, cleans path and can embed image data if :data-uri: attribute is enabled on document. Always use this method when dealing with image references. Relative image paths are resolved relative to document directory unless overridden using :imagesdir: |
icon_uri(path) | icon_uri(attr 'target') | Same as image_uri except it specifically works with icons. By default, it will look in the subdirectory images/icons, unless overridden using :iconsdir: |
media_uri(path) | media_uri(attr 'target') | Similar to image_uri, except it does not support embedding the data into the document. Intended for video and audio paths. |
normalize_web_path(path, relative_root) | normalize_web_path(attr('stylesheet'), attr('stylesdir', '')) | Joins the path to the relative_root and normalizes parent and self references. Access to parent directories may be restricted based on safe mode setting. |
normalize_system_path(path, relative_root, jail) | normalize_system_path(attr('stylesheet'), attr('stylesdir', ''), true) | The most critical method to ensure proper security. Joins the path to the relative_root and normalizes parent and self references. Access to parent directories may be restricted based on the safe mode setting. This method is extremely careful about assembling safe paths. |
In both Haml and Slim, you can assign an array to an HTML attribute and it will automatically be compacted (empty elements removed) and joined into a space-separated list.
For example:
%div{:id=>@id, :class=>['admonitionblock', (attr :name), role]}
Assuming id=foobar, name=warning, role=nil, the following element is produced:
<div id="foobar" class="admonitionblock warning">
If you assign a single value to an attribute, and the value is nil, the attribute will be excluded. Thus, if id is nil, then the output of the previous example would be:
<div class="admonitionblock warning">
The list block templates (block_olist, block_ulist and block_dlist) are responsible for handling their own direct children.
For example:
%ol{:class=>@style, :start=>(attr :start), :type=>(Asciidoctor::ORDERED_LIST_KEYWORDS[@style])}
- content.each do |item|
%li
%p=item.text
- if item.blocks?
=item.content
Hopefully that gets you going. I'll post more information as it comes to mind.
from asciidoctor-backends.
I have some additional notes on the following wiki page, though it's mostly just an outline:
https://github.com/asciidoctor/asciidoctor/wiki/APIs-for-Backend-Templates
from asciidoctor-backends.
Here's a rough and partially complete list of attributes:
https://github.com/asciidoctor/asciidoctor/wiki/Catalog-of-Document-Attributes
from asciidoctor-backends.
The best reference, atm, is the html5 backend in Haml. It's nearly feature complete to 0.1.4.preview.1.
https://github.com/asciidoctor/asciidoctor-backends/tree/master/haml/html5
from asciidoctor-backends.
@mojavelinux Those pieces of info are a great help. Thank you!
Contributions to @buuhsmead's efforts for the RevealJS backend are en route.
from asciidoctor-backends.
Awesome @jordanmccullough!
from asciidoctor-backends.
I've published a preview release of Asciidoctor 0.1.4. I recommend building the reveal.js backend against it as it has some improvements for making backend development easier. For example, you can now check for the existence of a role using role?
and get a list of all roles using roles
.
gem install asciidoctor --pre
I spoke to @jordanmccullough about speaker notes today. I think an admonition block + an ideal fit for this use case. Here's how I do it in dzslides:
[NOTE.speaker]
--
* AsciiDoc is easy to read in raw form.
* It's also easy to proof and edit.
* The punctuation was chosen to look like what it means.
* Only requires a text editor to read or write.
--
In the block_admonition.html.haml
template you can check for this role using:
- if role? 'speaker'
-# output HTML for speaker notes here
- else
-# normal admonition stuff
from asciidoctor-backends.
I wonder if role?
should be has_role?
and let role?
check for an exact match. Thoughts?
from asciidoctor-backends.
I'm all for explicitness, so I vote for has_role? returning whether it has
a role or not, assuming that's what you mean.
On Jul 6, 2013, at 5:49 PM, Dan Allen [email protected] wrote:
I wonder if role? should be has_role? and let role? check for an exact
match. Thoughts?
—
Reply to this email directly or view it on
GitHubhttps://github.com//issues/12#issuecomment-20563083
.
from asciidoctor-backends.
Added: asciidoctor/asciidoctor@34c91c7
from asciidoctor-backends.
Some additional useful info for creating custom backends:
from asciidoctor-backends.
Added by @cmoulliard with this commit: 18714c5
We'll use separate issues to track enhancements.
from asciidoctor-backends.
Related Issues (20)
- Invoking latex converter from elsewhere HOT 4
- Align chart extension with AsciiDoc conventions HOT 3
- Graduate the LaTeX backend to its own repository HOT 16
- README - populate "General Usage Instructions"
- Support for deckjs being in a different relative location HOT 2
- Include attribute to add third party javascript HOT 3
- No tags for the different releases HOT 2
- Support [%step] for source code HOT 2
- Only treat level-1 headings as sections in deck.js backend HOT 2
- Trim the ERB backend down to a handful of examples HOT 2
- Admonitions (TIP, NOTE...) are rendered in deck.js only as text, and without space HOT 1
- Is it there a backend that outputs to pure text? HOT 5
- Support new SVG embedding options HOT 1
- Should we deprecate this repository ? HOT 12
- if IE tag in Meta does not work since ie10 HOT 2
- How to access attr method from helpers.rb
- Problem: reveal.js backend wont generate Title slide HOT 6
- Problem: reveal.js backend wont apply themes from atttribute revealjs_theme HOT 4
- New backend for Remark HOT 4
- Enable Travis in this repo HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoctor-backends.