Code Monkey home page Code Monkey logo

asciidoctor / asciidoctor-extensions-lab Goto Github PK

View Code? Open in Web Editor NEW
104.0 104.0 101.0 336 KB

A lab for testing and demonstrating Asciidoctor extensions. Please do not use this code in production. If you want to use one of these extensions in your application, create a new project, import the code, and distribute it as a RubyGem. You can then request to make it a top-level project under the Asciidoctor organization.

License: Other

Ruby 66.64% CSS 31.60% HTML 0.20% JavaScript 1.55%

asciidoctor-extensions-lab's Introduction

Asciidoctor

Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in AsciiDoc. You can find the documentation for these projects at https://docs.asciidoctor.org.

In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment using Asciidoctor.js.

This document is also available in the following languages:
简体中文 | Deutsch | Français | 日本語

Latest Release library (API) docs Build Status (GitHub Actions) Project Chat (Zulip)

Sponsors

We want to recognize our sponsors for their commitment to improving the state of technical documentation by supporting this project. Thank you sponsors! Without your generous support, Asciidoctor would not be possible.

You can support this project by becoming a sponsor through OpenCollective.

AsciiDoc Processing and Built-in Converters

AsciiDoc is the language.
Asciidoctor is the processor.

Asciidoctor reads the AsciiDoc source, as shown in the panel on the left in the image below, and converts it to publishable formats, such as HTML 5, as shown rendered in the panel on the right.

Preview of AsciiDoc source and corresponding rendered HTML

Asciidoctor provides built-in converters for three output formats by default: HTML 5, DocBook 5, and man page (short for manual page). Additional converters, such as PDF and EPUB 3, are provided by separate gems. Asciidoctor also provides an out-of-the-box HTML experience complete with a default stylesheet and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).

Asciidoctor Ecosystem

Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it. Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js.

Installing an Asciidoctor processor is just the beginning of your publishing experience. Asciidoctor gives you access to a ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments:

Asciidoctor is the successor to AsciiDoc.py. If you’re using AsciiDoc.py, see Migrate from AsciiDoc.py to learn how to upgrade to Asciidoctor.

Requirements

Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of Ruby:

  • CRuby (aka MRI) 2.7 - 3.3

  • JRuby 9.2 - 9.4

  • TruffleRuby (GraalVM)

🔥

If you’re using a non-English Windows environment, you may bump into an Encoding::UndefinedConversionError when invoking Asciidoctor. To solve this issue, we recommend overriding the default external and internal character encodings to utf-8. You can do so by setting the RUBYOPT environment variable as follows:

RUBYOPT="-E utf-8:utf-8"

Once you make this change, all your Unicode headaches should be behind you.

If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. Asciidoctor is optimized to work with UTF-8 as the default encoding.

Installation

Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) named asciidoctor. The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle). Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).

Linux package managers

The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release.

If you want to use a version of Asciidoctor that’s newer than what is installed by the package manager, see the gem installation instructions.

apk (Alpine Linux)

To install the gem on Alpine Linux, open a terminal and type:

$ sudo apk add asciidoctor

pacman (Arch Linux)

To install the gem on Arch-based distributions, open a terminal and type:

$ sudo pacman -S asciidoctor

APT

On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. To install the package, open a terminal and type:

$ sudo apt-get install -y asciidoctor

DNF

On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. To install the package, open a terminal and type:

$ sudo dnf install -y asciidoctor

macOS

Homebrew

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions first.

Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type:

$ brew install asciidoctor

Homebrew installs the asciidoctor gem into an exclusive prefix that’s independent of system gems.

MacPorts

You can also use MacPorts, another package manager for macOS, to install Asciidoctor. If you don’t have MacPorts on your computer, complete the installation instructions first.

Once MacPorts is installed, you’re ready to install the asciidoctor gem via the Asciidoctor port. Open a terminal and type:

$ sudo port install asciidoctor

Windows

To use Asciidoctor with Windows, you have two options.

Chocolatey

When you already use chocolatey on your machine, you can use:

choco install ruby

Rubyinstaller

Or you use the Rubyinstaller, download the package for your Windows Version and after the installation go ahead with gem installation instructions.

gem install

Before installing Asciidoctor using gem install, you should set up RVM (or similar) to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem, or any other gem for that matter. When using RVM, gems are installed in a location isolated from the system. (You should never use the gem command to install system-wide gems).

Once you’ve installed Ruby using RVM, and you have activated it using rvm use 3.0, open a terminal and type:

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

Bundler

  1. Create a Gemfile in the root folder of your project (or the current directory)

  2. Add the asciidoctor gem to your Gemfile as follows:

    source 'https://rubygems.org'
    gem 'asciidoctor'
    # or specify the version explicitly
    # gem 'asciidoctor', '2.0.22'
  3. Save the Gemfile

  4. Open a terminal and install the gem using:

    $ bundle

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.

Upgrade

If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don’t need to update the gem manually.

apk (Alpine Linux)

To upgrade the gem, use:

$ sudo apk add -u asciidoctor

APT

To upgrade the gem, use:

$ sudo apt-get upgrade -y asciidoctor

DNF

To upgrade the gem, use:

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

To upgrade the gem, use:

$ brew update
$ brew upgrade asciidoctor

MacPorts (macOS)

To upgrade the gem, use:

$ sudo port selfupdate
$ sudo port upgrade asciidoctor

gem install

If you previously installed Asciidoctor using the gem command, you’ll need to manually upgrade Asciidoctor when a new version is released. You can upgrade the gem by typing:

$ gem install asciidoctor

When you install a new version of the gem using gem install, you end up with multiple versions installed. Use the following command to remove the old versions:

$ gem cleanup asciidoctor

Usage

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it’s available, run the following in your terminal:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.22 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

Command line interface (CLI)

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html.

$ asciidoctor README.adoc

You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:

$ asciidoctor --help

For instance, to write the file to a different directory, use:

$ asciidoctor -D output README.adoc

The asciidoctor man page provides a complete reference of the command line interface.

Refer to the following resources to learn more about how to use the asciidoctor command.

Ruby API

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

To use Asciidoctor in your application, you first need to require the gem:

require 'asciidoctor'

You can then convert an AsciiDoc source file to an HTML file using:

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
⚠️
When using Asciidoctor via the API, the default safe mode is :secure. In secure mode, several core features are disabled, including the include directive. If you want to enable these features, you’ll need to explicitly set the safe mode to :server (recommended) or :safe.

You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

If you want the full HTML document, enable the header_footer option as follows:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

If you need access to the parsed document, you can split the conversion into discrete steps:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

Keep in mind that if you don’t like the output Asciidoctor produces, you can change it! Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.

One easy way to customize the output piecemeal is by using the template converter. The template converter allows you to supply a Tilt-supported template file to handle converting any node in the document.

However you go about it, you can have 100% control over the output. For more information about how to use the API or to customize the output, see:

Contributing

New contributors are always welcome! If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix.

Here are some ways you can contribute:

  • by using prerelease (alpha, beta or preview) versions

  • by reporting bugs

  • by suggesting new features

  • by writing or editing documentation

  • by writing code with tests — No patch is too small.

    • fix typos

    • add comments

    • clean up inconsistent whitespace

    • write tests!

  • by refactoring code

  • by fixing issues

  • by reviewing patches

The Contributing guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.

Getting Help

Asciidoctor is developed to help you easily write and publish your content. But we can’t do it without your input. If you need assistance or want to provide feedback, please follow the links to the resources listed on the Get Help page in the docs. Here’s a quick summary:

Project chat (Zulip)

https://chat.asciidoctor.org

Discussion list (archived)

https://discuss.asciidoctor.org

Social media (Twitter)

Follow @asciidoctor or search the #asciidoctor hashtag

Further information and documentation about Asciidoctor can be found on the project’s website.

Home | News | Docs

The Asciidoctor organization on GitHub hosts the project’s source code, issue tracker, and sub-projects.

Code of Conduct

The core Asciidoctor project is governed by the Code of Conduct for the Asciidoctor community of projects. By participating, you’re agreeing to honor this code. Let’s work together to make this a welcoming, professional, inclusive, and safe environment for everyone.

Versioning and Release Policy

This project adheres to semantic versioning (major.minor.patch). Typically, patch releases are only made for the current minor release. However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.

Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. Use of this software is granted under the terms of the MIT License.

See the LICENSE for the full license text.

Authors

Asciidoctor is led by Dan Allen and Sarah White and has received contributions from many individuals in Asciidoctor’s awesome community. The project was initiated in 2012 by Ryan Waldron based on a prototype written by Nick Hengeveld for the Git website.

AsciiDoc.py was started and maintained by Stuart Rackham from 2002 to 2013 and has received contributions from many individuals in the AsciiDoc.py community.

Trademarks

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.

Changelog

Refer to the CHANGELOG for a complete list of changes in older releases.

asciidoctor-extensions-lab's People

Contributors

alterakey avatar atishay avatar bk2204 avatar bulletmark avatar culyun avatar danyill avatar edusantana avatar ggrossetie avatar liljenstolpe avatar lordofthejars avatar maxandersen avatar mojavelinux avatar nicorikken avatar nightscape avatar petk avatar smurfz87 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

asciidoctor-extensions-lab's Issues

Create an extension to execute JavaScript code in the browser

This could be really useful when writing documentation for a JavaScript library.
The extension will search for JavaScript source code blocks and add a link/button "Run this code in your browser" to execute the code and print the result in the browser.

Multipage html5 converter breaks ToC support

With the help of #56 and by removing the hardcoded noheader attribute I tried to add ToCs in the chunked html files to no avail.

It looks like the multipage-html5-converter extension breaks :toc: handling somehow.

Extension for Sign languages

Hi,

I'm trying to write a extension for placing videos from a Sign Language. It would be some thing like this:

libras.yaml:

"casa": https://www.youtube.com/watch?v=xjxjTMBoNjE

sample.adoc:

:sign-lang: libras

sign::casa[]

It would read casa from libras.yaml and translate to:

video::https://www.youtube.com/watch?v=xjxjTMBoNjE[]

It would be more complex, but this would be a start.

Can someone help me?

Here's what I have done so far:

  • I think it would be a subclasse of BlockMacroProcessor, like gist-block-macro
  • A made a copy of gist-block-macro and replace gist to sign:
(...)
class SignBlockMacro < Extensions::BlockMacroProcessor
  use_dsl

  named :sign
(...)

sample.adoc

= Sign Block Macro Extension

.Guard setup to live preview AsciiDoc output
sign::mojavelinux/5546622[]
  • And I run it with -r:
asciidoctor-extensions-lab$ asciidoctor --trace -r lib/sign-languages/extension.rb lib/sign-languages/sample.adoc  
/home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- lib/sign-languages/extension.rb (LoadError)
    from /home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require'

  • It didn't work. So I have tests gist alone:
asciidoctor-extensions-lab$ asciidoctor --trace -r lib/gist-block-macro/extension.rb lib/gist-block-macro/sample.adoc 
/home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- lib/gist-block-macro/extension.rb (LoadError)
    from /home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require'
  • Since I don't know if gist is working, then I have tested an other BlockMacroProcessor extension, the TreeBlockMacro. I changed the sample file to directory of mine, and tested it:
asciidoctor-extensions-lab$ asciidoctor --trace -r lib/tree-block-macro/extension.rb lib/tree-block-macro/sample.adoc 
/home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- lib/tree-block-macro/extension.rb (LoadError)
    from /home/santana/.rvm/rubies/ruby-2.2.1/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require'

Can someone guide me? What I am doing wrong?

How do we use these extensions?

Asciidoctor version 1.5.2 mentions, in the help, an option to require ruby modules before running

    -r, --require LIBRARY            require the specified library before executing the processor (using require)
                                     may be specified more than once

I guess this can be used to load these extensions from the command line but I can't find any documentation about this. Especially it's not mentioned either here or here.

Align chart extension with AsciiDoc conventions

To be consistent with the <name>::<target>[<attributes>] convention, I think we should change the placement of arguments so the data is <target> and the chart type is the first positional attribute. I think chart type should default to "line" if not specified.

chart::sample.csv[line]

chart::sample.csv[bar]

chart::sample.csv[step]

chart::sample.csv[spline]

I think we should also support positional attributes for x and y label as well as size.

chart::<data-uri>[<type>,<x-label>,<y-label>,<width>,<height>]

We should also support a block form where the data is specified in a literal block:

[chart,line]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

It will be necessary to register separate extensions for the block macro and block forms, but they can share common code.

ChartBlockMacro weird output

Hi,

I want to build chart-block-macro, after build I'm getting only

/* Generated by Opal 0.6.3 */
(function($opal) {
  var $a, $b, TMP_1, self = $opal.top, $scope = $opal, nil = $opal.nil, $breaker = $opal.breaker, $slice = $opal.slice;

  self.$require_relative("chart-block-macro/extension");
  return ($a = ($b = $scope.Extensions).$register, $a._p = (TMP_1 = function(){var self = TMP_1._s || this, $a;

  if ((($a = self.$document()['$basebackend?']("html")) !== nil && (!$a._isBoolean || $a == true))) {
      return self.$block_macro($scope.ChartBlockMacro)
      } else {
      return nil
    }}, TMP_1._s = self, TMP_1), $a).call($b);
})(Opal);

What can be the reason?

Simple Tree Gen

I want to add simple tree diagrams to a text. Is possible to add an easy tree generation feature.

E.g.

- level 1 (A)
-- child of level A (B)
---  child of B
-- 2nd child of A
- 2nd child of root

Add list of tables and list of figures

In many documents it is needed to have list of figures and list of tables right below table of contents. Would be good to have this feature in asciidoctor-pdf

Document how to create a new admonition type

I think it's an extension I need, but I'm not sure how to go about making one. Here's what I need:

I am converting a text book to various e-formats and the book has several in-text devices. Up till now I have been using the built-in admonitions and just created a new stylesheet to use different icons to match what I need. However, it seems to me that rather than subverting the existing admonitions it would be better to create new custom blocks for this project. For example, I need a block that looks and behaves exactly like an admonition except that it should be called thinkspot rather than tip, caution, warning, or note.

Can someone give me a step-by-step on what to do?

Thanks!

Create lint extension

That way writers could ensure that theirs documents respect conventions and best practices. @mojavelinux I'm sure you already have a list of best practices ? 😄

Then it would be great to let users configure rules with a simple config file.

Rendering dlists with multipage.rb

I'm using the multipage converter to create chunked output. I ran into some issues trying to get the following markup to render properly:

##### Example title

pipeline.<name>.example::

Example text
+
*Required.*
+
.Example
----
# pipeline configuration
pipeline.example.quorum = \
----

I'd only get the title of this in the output. I think this can be addressed by the reparenting function here: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/multipage-html5-converter.rb#L60. I think it maybe sufficient to add something like:

      if block.context == :dlist
        block.parent = parent
      end

after the recursive call to reparent. Adding that I started getting the output that I expected. Not sure if this is the right approach.

showcomments-preprocessor seems broken with latest asciidoctor

Running:

asciidoctor -r ./lib/showcomments-preprocessor.rb lib/showcomments-preprocessor/sample.adoc

gives me:

/Users/max/code/asciidoctor-extensions-lab/lib/showcomments-preprocessor.rb:4:in `<top (required)>': uninitialized constant Extensions (NameError)
	from /Users/max/.rvm/rubies/ruby-2.3.3/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
	from /Users/max/.rvm/rubies/ruby-2.3.3/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:230:in `block in parse!'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:228:in `each'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:228:in `parse!'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:33:in `parse!'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/invoker.rb:22:in `initialize'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/bin/asciidoctor:12:in `new'
	from /Users/max/.rvm/gems/ruby-2.3.3/gems/asciidoctor-1.5.6.1/bin/asciidoctor:12:in `<top (required)>'
	from /Users/max/.rvm/gems/ruby-2.3.3/bin/asciidoctor:23:in `load'
	from /Users/max/.rvm/gems/ruby-2.3.3/bin/asciidoctor:23:in `<main>'
	from /Users/max/.rvm/gems/ruby-2.3.3/bin/ruby_executable_hooks:15:in `eval'
	from /Users/max/.rvm/gems/ruby-2.3.3/bin/ruby_executable_hooks:15:in `<main>'

Create extension to detect merge conflicts

Create an extension to detect merge conflicts in AsciiDoc source files.

With large commits, it's easy to miss some conflict and accidentally commit it. Example here:

http://gist.asciidoctor.org/?e4b59c5f6b0a85689859

When this happens in source code, the compiler or a test will normally tell you. If Asciidoctor could detect the pattern and tell you (aka fail the build), that would be great. This could likely be handled by a Preprocessor extension.

Create extension or add-on script that extracts revision history from git history

Create either an extension or an add-on script that extracts the revision history from the git history.

The idea is to only store the latest revision number and corresponding remark in the document itself. Whenever the revision number is changed, you commit the change. Then, you can get a full history of revision numbers and corresponding remarks by walking the git history and looking for when then revision number changes. Create a catalog, then output it to a temporary docinfo file. Finally, convert as normal with the docinfo enabled.

asciidoc-coalescer.rb ignores attributes in file

This is a very minor issue, since it's got such an easy workaround, but I'm reporting it anyway.

If I have a doc with conditional formatting based on ifdef::[], the script ignores the attributes set in the file. They have to be passed via the command line. I would expect the following file to give me the english version when passed through the script, but it just gives me blank output. If I do ruby asciidoc-coalescer.rb -a en file.ad, however, I get the correct output.

:en:

ifdef::en[]
== My Document
English version

include::[some-file-en.ad]
endif::en[]

ifdef::pt[]
== Meu Documento
Versão em portugûes

include::[some-file-pt.ad]
endif::pt[]

Modify parsing options from an extension

I tried creating an extension that would generate HTML ready to be pasted into a Wordpress post in source form (minimal HTML).

For it to work without setting the --no-header-footer in addition to the -r flag I would have liked to set the :header_footer = false option directly when the extension is registered.

I've tried several ways and it didn't work. Including subclassing and overloading initialize and trying to access the @options field and add the option to it (but the hash is frozen).

I need guidance. Here's the code with attempts commented out: https://github.com/asciidoctor/asciidoctor-extensions-lab/compare/master...obilodeau:wordpress-extension?expand=1

Use require when running with Opal

Example:

RUBY_ENGINE == 'opal' ? (require 'man-inline-macro/extension') : (require_relative 'chrome-inline-macro/extension')

We can revert this change as soon as Opal 0.7.0 is released.

"Standard" way to overload assets path

When using extension(.js) in the chrome extension, assets are stored within the extension package and the URL is chrome-extension://<EXTENSION_ID>/.

I think it would be nice to have a standard way to overload assets path.

Add links to navigate extensions in README

It's hard to navigate the repository because some extensions are defined an an extension.rb file and some are defined in the main extension file. Add links to each extension listed in the README to navigate to each of the following files:

  • registration
  • extension code
  • sample

In some case, the registration and extension code are the same file.

Create text hyphenation extension

Create an extension that inserts shy hyphens into text by passing the text through a library such as text-hyphen. The result is that justified text can be hyphenated at logical locations so that the spread of words is more even.

The output will work with the existing styles in the default Asciidoctor stylesheet. Here's a screenshot that demonstrates how it would look:

image

RunKit Code Block Processor

RunKit is a tool to try Node.js in the browser. It is wired to Node package registry – npm.

capture d ecran 2017-03-05 a 19 17 33

I imagine something like this:

[source,javascript,runkit="nodeVersion:6"]
----
const lodash = require("lodash");

lodash.camelCase('get content');
----

becomes interactive as https://runkit.com/oncletom/58bc55b33cdd1a0013ae1a89 by pressing the Run in browser button (like the View Results extension).

<script src="https://embed.runkit.com"></script>
<script>
document.querySelectorAll('[data-runkit]').forEach(el => {
  RunKit.createNotebook({
    element: el,
    source: el.querySelector("code").textContent
  });
});
</script>

// ...

<pre class="javascript" data-runkit data-runkit-version="6"><code>
const lodash = require("lodash");

lodash.camelCase('get content');
</code></pre>

RunKit documentation is available here: https://runkit.com/docs/embed

cc @Mogztter

Conditional statements are not working when I use preprocessor extensions

Conditional statements are not working when I use 'mathematical-treeprocessor' extension.
The "hello world" string doesn't apear when using 'preprossor extension'.

:enable-string:

ifdef::enable-string[]
hello world!
endif::[]

Conditional statements are working well when I delete mathematical-preprocessor code on 'mathematical-treeprocessor.rb'.

Extensions.register do
  # if @document.basebackend? 'html'
  //inline_macro MathematicalInlineMacro
  treeprocessor MathematicalTreeprocessor
end

I've tested several other preprocessors, it's same on other preprocessors make same problem too.

Conditional statements which looks for CLI attributes works well.
Only conditional satements which looks for DOCUMENT attributes are not working.

Subsection offset - parent needed

Contents

  • PROBLEM
  • EXAMPLE
  • HTML Output
  • Code

@mojavelinux, could you take a look at the below?

PROBLEM: Add offsets for subsections

In the example below a modification to sectnumoffset-treeprocessor.rb is used to offset subsection
numbers in the first section that is processed. I would like to insert a parent section at the head
of the document and eliminate the text == Outer Test\n so that the first line of the
HTML output is

<h3 id="_inner_test_a">2.3. Inner Test A</h3>

Help is needed from the Ascii Doctor.

EXAMPLE:

require 'asciidoctor-latex'
source = "== Outer Test\n=== Inner Test A\n$a^2 = 1$\n\n=== Inner Test B\nfoo\n\n== Outer again\nho ho ho!\n\n=== Yikes!"

puts Asciidoctor.convert(source, backend: 'html5', attributes: 'sectnums sectnumoffset=1  subsectnumoffset=2')

HTML output:

[~/dev/asciidoctor-latex/work] ruby-2.2.2 $ ruby y.rb   
subsectnumoffset: 2
Insert parent section at 'head' of document with offset 1
<div class="sect1">
<h2 id="_outer_test">2. Outer Test</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_inner_test_a">2.3. Inner Test A</h3>
<div class="paragraph">
<p>\(a^2 = 1\)</p>
</div>
</div>
<div class="sect2">
<h3 id="_inner_test_b">2.4. Inner Test B</h3>
<div class="paragraph">
<p>foo</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_outer_again">3. Outer again</h2>
<div class="sectionbody">
<div class="paragraph">
<p>ho ho ho!</p>
</div>
<div class="sect2">
<h3 id="_yikes">3.1. Yikes!</h3>

</div>
</div>
</div>

CODE:

Extensions.register do
  # A treeprocessor that increments each level-1 section number by the value of
  # the `sectnumoffset` attribute.
  #
  # In addition, if `subsectnumoffset` is defined and greater than zero,
  # the numbers of subsections in the first section encountered will
  # be incremented by the offset.
  #
  # The numbers of all subsections will be
  # incremented automatically since those values are calculated dynamically.
  #
  # Run using:
  #
  # asciidoctor -r ./lib/sectnumoffset-treeprocessor.rb -a sectnums -a sectnumoffset=1 lib/sectnumoffset-treeprocessor/sample.adoc
  #
  #
  treeprocessor do
    process do |document|
      if (document.attr? 'sectnums') && (sectnumoffset = (document.attr 'sectnumoffset', 0).to_i) > 0
        subsectnumoffset = (document.attr 'subsectnumoffset', 0).to_i
        warn "subsectnumoffset: #{subsectnumoffset}".red
        section_count = 0
        if subsectnumoffset > 0
          warn "Insert parent section at 'head' of document with offset #{sectnumoffset}".cyan
        end
        ((document.find_by context: :section) || []).each do |sect|
          next unless sect.level <= 2
          if sect.level == 1
            section_count += 1
            sect.number += sectnumoffset
          elsif sect.level == 2 && section_count == 1
            sect.number += subsectnumoffset
          end
        end
      end
      nil
    end
  end
end

How to access command line params from Preprocessor

I am planning to write a preprocessor to parse attributes from a yaml file as described in 566. In order to maximize the use of the config file, I am planing to implement a theme feature from the config file, which contains common attributes (overidable) and theme specific attributes.
Example:

linkcss: true
copycss: true
stylesdir: styles
themes:
   bright:
      stylesheet: asciidoctor
      source-highlighter: highlight.js
      highlightjs-theme: atom
   dark:
      stylesheet: asciidoctor-dark
      source-highlighter: highlight.js
      highlightjs-theme: monokai

Then the cli command is asciidoctor --config-file=conf.yml --theme=dark -a stylesdir=new_style input.adoc.

The order of the attributes is cli > theme > common. It's easier to implement theme > common, but for cli > theme, config-file and theme, the preprocessor need to read the command params.

Cross compile gist-block-macro

The current gist-block-macro extension is not cross compiling well with Opal.
I don't know the reason behind but when I replaced registry.document with @document everything work as expected.

Given that other extensions favor @document over registry.document I think it's a good idea to stick with @document (shorter).

Create a proper README for the extensions lab

We need a README for this repository that covers (at least) the following information:

  1. What extensions are available here
  2. How to load an extension from the extension lab

We should also cover how these extensions are organized to help people create new ones.

This is a follow-up from the question posed in #35.

Rename registration files

It would be more verbose to rename files inside lib/*.rb to include registration in their names:

lib/chart-block-macro-registration.rb
lib/chrome-inline-macro-registration.rb
lib/copyright-footer-postprocessor-registration.rb
lib/emoji-inline-macro-registration.rb
(...)

It would avoid errors like #45.

Unit test extension for source blocks

It would be interested to demonstrate how to create an extension for AsciiDoc that ran through all the source listings and verified the expected output. This is an inside-out-approach from pulling snippets from a test suite. Different circumstances call for different approaches.

Since the extension has to run the assertions, it will likely be language-specific. We should focus on Ruby or JavaScript in the example.

Here's the inspiration for this extension (though it uses really quirky syntax which I'd like to improve on).

http://www.jspatterns.com/unit-testing-in-asciidoc/

Create DocinfoProcessor for embedding JavaScript files in HTML output

Create a DocinfoProcessor extension for embedding JavaScript files in generated HTML output.

For example:

:javascripts: myjavascript.js

Converts into :

<script type='text/javascript' src='myjavascript.js'></script>

The javascripts attribute can be a comma-separated list of paths. We may also want to specify the location of the JavaScript file explicitly.

:header_javascripts: ...
:footer_javascripts: ...

The default should probably be header.

Create chart block extension

Add a block extension to demonstrate how to output a chart using the content of the block as the data. One idea is using chart.js or d3.js.

Create an extension to generate a changelog

The idea is to be able to generate a changelog:

We could even support multiple SCM. For instance, if we want to display the Git changelog of a project, between master and version 1.0.0:

changelog:git[master..v1.0.0]

Create summaries from distributed definitions

OK, couldn't find a better title... Here is what I want to do:
I am writing technical machine (not software :-) ) documentation using asciidoctor on atom. The machines are described by elements. With the element it is suitable to define the required maintenance work. Could be a small table, an admonition, ... whatever.

While for the writer it is suitable to have the maintenance described with the element, it is more suitable for the maintenance person to have a maintenance summary list at the end of the document.

I came up with tags and a self-including document, see code snippet below. Any better idea?

= Title

== Motor

Content not part of the maintenance tag

|===
| Element | Maintenance Instruction | Frequency

// tag::Maintenance[]
| icon:Maintenance[] <<Motor>> Oil | Change Motor Oil, use for salad | Daily
// end::Maintenance[]
|===

== Extruder

|===
| Element | Maintenance Instruction | Frequency

// tag::Maintenance[]
| icon:Maintenance[] <<Extruder>> Screw | Make nice & shiny | Before go to sleep
// end::Maintenance[]
|===


== Maintenance Summary

|===
| Element | Maintenance Instruction | Frequency

include::Source.adoc[tag=Maintenance]

|===

mathoid-treeprocessor error in svg

Been trying to get a compilation path that will render a document with math in it across html, pdf, epub, and mobi. Managed to get mathoid-treeprocessor installed after some tinkering.

Using the sample .adoc file:

= _Precompiled_ Math!

[stem#equation1]
++++
"d"(bbp,bbq) = sqrt((p_1 - q_1)^2 + (p_2 - q_2)^2)
++++

and the command:

asciidoctor  -r asciidoctor-pdf -r ./lib/mathoid-treeprocessor  -b pdf test.adoc --trace

I get the following output:

asciidoctor: WARNING: could not embed image: /Volumes/SSD Disk/git Repos/test/equation1.svg; Duplicate attribute "xlink:href"
Line: 23
Position: 7155
Last 80 unconsumed characters:

The generated svg file is not an equation but text containing an error message "This page contains the following errors..."

Running phantomjs main.js with the query string http://localhost:16000/?q=x^2&type=asciimath generates a web page in the browser saying:

This page contains the following errors:

error on line 1 at column 1252: Attribute xlink:href redefined
Below is a rendering of the page up to the first error.

The page source is:

<svg xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="-22 -915.1157009464328 932.0389244992066 953.2641499988939" style="width: 2.167ex; height: 2.167ex; vertical-align: -0.135ex; margin: 1px 0px; position: static;" xmlns="http://www.w3.org/2000/svg"><defs id="MathJax_SVG_glyphs"><path id="STIXWEBMAINI-78" stroke-width="10" d="M243 355l12 -57c70 107 107 143 151 143c24 0 41 -15 41 -37c0 -21 -14 -36 -34 -36c-19 0 -28 17 -52 17c-18 0 -54 -44 -98 -121c0 -7 2 -21 8 -45l32 -134c7 -28 16 -41 30 -41c13 0 24 10 47 40c9 12 13 18 21 28l15 -9c-58 -90 -84 -114 -122 -114 c-32 0 -47 18 -59 68l-29 119l-88 -119c-44 -59 -64 -68 -95 -68s-50 16 -50 42c0 20 14 36 34 36c9 0 19 -4 32 -11c10 -6 20 -9 26 -9c11 0 30 19 51 49l82 116l-28 124c-14 60 -21 68 -46 68c-8 0 -20 -2 -39 -7l-18 -5l-3 16l11 4c61 22 94 29 117 29 c25 0 37 -18 51 -86Z"></path><path id="STIXWEBMAIN-32" stroke-width="10" d="M474 137l-54 -137h-391v12l178 189c94 99 130 175 130 260c0 91 -54 141 -139 141c-72 0 -107 -32 -147 -130l-21 5c21 117 85 199 208 199c113 0 185 -77 185 -176c0 -79 -39 -154 -128 -248l-165 -176h234c42 0 63 11 96 67Z"></path></defs><g stroke="black" fill="black" stroke-width="0" transform="matrix(1 0 0 -1 0 0)"><use xlink:href="#STIXWEBMAINI-78" xlink:href="#STIXWEBMAINI-78"></use><use transform="scale(0.7071067811865476)" xlink:href="#STIXWEBMAIN-32" x="640" y="583" xlink:href="#STIXWEBMAIN-32"></use></g></svg>

Any ideas?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo 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.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.