middleman / middleman-asciidoc

:beginner: AsciiDoc support for Middleman 4. (In Middleman 3, AsciiDoc support is provided by a core extension).

Middleman - Makes developing websites simple

Middleman is a static site generator using all the shortcuts and tools in modern web development. Check out middlemanapp.com for detailed tutorials, including a getting started guide.

Why Middleman?

These days, many websites are built with an API in mind. Rather than package the frontend and the backend together, both can be built and deployed independently using the public API to pull data from the backend and display it on the frontend. Static websites are incredibly fast and require very little RAM. A front-end built to stand-alone can be deployed directly to the cloud or a CDN. Many designers and developers simply deliver static HTML/JS/CSS to their clients.

• Uses Sass for DRY stylesheets.
• Bring your own asset pipeline (WebPack, Babel, Sprockets or any other).
• Easy templating with ERb or Haml.

Middleman gives the stand-alone developer access to all these tools and many, many more.

Installation

Middleman is built on Ruby and uses the RubyGems package manager for installation. These are usually pre-installed on Mac OS X and Linux. Windows users can install both using RubyInstaller. For windows RubyInstaller-Devkit is also required.

gem install middleman

Getting Started

Once Middleman is installed, you will have access to the middleman command. First, let's create a new project. From the terminal:

middleman init MY_PROJECT

This will create a new Middleman project located in the "MY_PROJECT" directory. This project contains a config.rb file for configuring Middleman and a source directory for storing your pages, stylesheets, javascripts and images.

Change directories into your new project and start the preview server:

cd MY_PROJECT
middleman server

The preview server allows you to build your site, by modifying the contents of the source directory, and see your changes reflected in the browser at: http://localhost:4567/

To get started, simply develop as you normally would by building HTML, CSS, and Javascript in the source directory. When you're ready to use more complex templates, simply add the templating engine's extension to the file and start writing in that format.

For example, say I am working on a stylesheet at source/stylesheets/site.css and I'd like to start using Compass and Sass. I would rename the file to source/stylesheets/site.css.scss and Middleman will automatically begin processing that file as Sass. The same would apply to CoffeeScript (.js.coffee), Haml (.html.haml) and any other templating engine you might want to use.

Finally, you will want to build your project into a stand-alone site. From the project directory:

middleman build

This will compile your templates and output a stand-alone site which can be easily hosted or delivered to your client. The build step can also compress images, employ Javascript & CSS dependency management, minify Javascript & CSS and run additional code of your choice. Take a look at the config.rb file to see some of the most common extensions which can be activated.

Learn More

A full set of in-depth instructional guides are available on the official website at: http://middlemanapp.com.

Additionally, up-to-date generated code documentation is available on RubyDoc.

Community

The official community forum is available at: http://forum.middlemanapp.com

Bug Reports

Github Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems: https://github.com/middleman/middleman/issues

The best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit Pull Requests containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.

How to Run Cucumber Tests

1. Checkout Repository: git clone https://github.com/middleman/middleman.git
2. Install Bundler: gem install bundler
3. Run bundle install inside the project root to install the gem dependencies.
4. Run test cases: bundle exec rake test

Donate

Click here to lend your support to Middleman

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision. For example:

gem 'middleman', '~> 4.0'

License

Copyright (c) 2010-2023 Thomas Reynolds. MIT Licensed, see LICENSE for details.

middleman-asciidoc's Issues

Use outfilesuffix as requested by Asciidoctor

Rather than hard-coding the extension for output files as .html, use the outfilesuffix as requested by Asciidoctor. This is typically .html, but opens the door for allowing Asciidoctor to produce other types of content.

Allow base_dir option to be specified

Allow the base_dir option to be specified when activating the AsciiDoc extension. The default value should be nil, which should track the docdir of the current document being processed.

Example:

activate :asciidoc, base_dir: app.source_dir.expand_path

The default should track the docdir of the document being processed so the AsciiDoc processor behaves in the normal way.

Error when using middleman-search with directory indexes

In my current setup I am trying to use middleman-search together with directory indexes and asciidoc.

While using that I am getting this error:
undefined method destination_path' for nil:NilClass C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/middleman-asciidoc-1.0.0/lib/middleman-asciidoc/template.rb:14:in prepare'
C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/tilt-2.0.8/lib/tilt/template.rb:99:in initialize' C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/tilt-2.0.8/lib/tilt/mapping.rb:138:in new'
C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/tilt-2.0.8/lib/tilt/mapping.rb:138:in new' C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/tilt-2.0.8/lib/tilt.rb:43:in new'

The problem is that the current page that needs to be rendered by asciidoc is not having a resource but only the :current_path. middleman-search runs through the sitemap and renderes all found resources like this:

https://github.com/manastech/middleman-search/blob/master/lib/middleman-search/search-index-resource.rb

html = resource.render( { :layout => false }, { :current_path => resource.path } )
Nokogiri::HTML(html).xpath("//text()").text

The problem is that some of the resources in the sitemap are not found by the TemplateContext.current_resource by the :current_path when directory index is used.

Is it possible to change the middleman-asciidoc to render also by the provided path and not by calling resource.destination_path anymore when there is no resource?

Regards
Lasse

Document how to make additional site- attributes available to AsciiDoc document

Middleman does not have a standard category in the template model for site data. However, this is often a category site authors end up introducing into their site. Document how to make data in the site category available to the template model.

Include paths incorrect

Hola,

I'm using the following gem versions:

gem 'middleman', github: 'middleman', branch: 'v3-stable'
# ...
gem 'asciidoctor', '~> 1.5.0'

I have created the following .adoc files (e.g.);

/source/docs/my-file.adoc
/source/docs/includes/common/other-file.adoc
/source/docs/includes/my-doc/other-file2.adoc
/source/docs/images/image.png

I am running into difficulty when building with this structure, it seems the includes/images are not sourced from the correct directory and so I get errors like:

asciidoctor: WARNING: <stdin>: line 9: include file not found: /Users/fred/Projects/foobar/source/includes/common/other-file.adoc

and in the resulting my-file.html:

Unresolved directive in <stdin> - include::includes/common/other-file.adoc[]

I've tried to pass values for docdir etc. to the asciidoc command but to no avail. Is there a standard way of achieving this result, preferable only building the files in /source/docs/*.adoc (that is, not building the other include files and adding them to the sitemap).

Much appreciated.

Set 'lang' attribute based on the locale of the page

Currently, an AsciiDoc document cannot conveniently obtain current_page.options[:locale] set by the I18n extension, and it seems natural for it to be reflected in the 'lang' attribute since its standard (and used by some converters).

It would be better if we are able to specify translation strings based on the locale, either obtaining them from the I18n extension or set from configuration or data files.

Set env attribute to site instead of middleman

Set the env attribute to site instead of middleman. This aligns with the behavior of plugins for other static site generators, such as Awestruct and Jekyll.

Here's a full list of environment-related attributes to set:

env=site
env-site
site-gen=middleman
site-gen-middleman
middleman-version=[value of Middleman::VERSION]

Don't fail if value of attribute is not a string

Don't fail when merging attributes if value of attribute is not a string.

Example:

activate :asciidoc do |asciidoc|
  asciidoc.attributes = { 'sectnumlevels' => 2 }
end

Generate standalone document when page-layout is unset

When the page-layout attribute is unset, Asciidoctor should generate a standalone HTML document for Middleman to serve.

= Page Title
:page-layout!:

As part of this change, middleman-asciidoc should recognize when the page-layout attribute is explicitly unset. That is done by passing page-layout=@ to Asciidoctor so the attribute entry effectively unassigns the default value.

A blank value for page-layout should activate the auto layout feature in Middleman.

Drop support for global attributes config key

Drop support for the global config key :asciidoc_attributes. For example:

set :asciidoc_attributes, ['source-highlighter=coderay']

This was the pre-Middleman 4 way of configuring an extension. The modern way of configuring an extension is to pass a key (attributes) to the activate function, which is already supported by this extension.

Tip/Note images not rendered?

Probably a stupid one but I'm scratching my head trying to work out how to get the Tip/Note images to render. Right now I'm using the default CSS file which is producing textual output for these elements (see here: https://www.apachefriends.org/docs/hosting-xampp-on-azure.html).

I can see in the example asciidoc pages (below) that these images are rendered with <img/> tags, so I'm guessing it's not just a case of missing CSS.

Thanks

Create a middleman template project for AsciiDoc

Create a middleman template project for AsciiDoc that can be used to initialize a new Middleman site with AsciiDoc enabled.

https://github.com/middleman/middleman-templates-default

Asciidoc Diagram

And one more question:

Is there also a way to influence the url of a generated diagram , like

[ditaa,somepic,png]
----
=====>
----

which will result in /images/somepic.png

but I would like it to be an a) absolute path and b) possible asset hashed? so www.mysite.com/images/somepic-ABCDEFG.png

?

Make document object available to template

Make the Asciidoctor::Document object for the current page (AsciiDoc document) available to the template as document. This allows the template to consult the document structure and add page-specific elements to other regions of the UI. One example is a sidebar table of contents.

If there is a cost associated with this behavior, it should be concealed behind an option.

Problems rendering a custom toc / block_outline.html.slim

Hi @mojavelinux ,
I've got a Middleman 4.2.1 project, with a
\source\_asciidoc_templates\block_outline.html.slim file (Link), which I copied from the asciidoctor-backends project.

Furthermore I have a layout file, which calls the following method:

<div class="sidebar">
  <% if (doc = current_page.data.document) %>
    <%= doc.converter.convert doc, 'outline', toclevels: 3 %>
   <% end %>
</div>

Now i know that the block_outline.html.slim file is getting applied correctly (i.e. I also made the necessary changes to config.rb), because I get the following error message when trying to render my pages:

undefined method `section_level' for #Asciidoctor::Document:0x007fffe50b9ea0 Did you mean? sections

Ruby | /mnt/c/dev/blah/source/_asciidoc_templates/block_outline.html.slim: in block in singleton class, line 3

What am I missing? Why does it not find the helper appropriate helper methods?

Thank you!
Marco

Store author information in author model

Use an author model to store author information for the current page. The model should include name, which is required, and email or url, if specified.

To maintain backwards capability with existing templates, the #to_s method should be defined to return the name.

Support special keywords for base_dir setting

Support the following two keywords for the base_dir setting:

• :source - Resolves to the site source directory
• :docdir - Resolves to the directory of the current document

If the value of this setting is nil, it should simply be ignored. The default value for this setting should be changed from nil to :docdir.

NOTE: This change aligns with the behavior of the Jekyll plugin.

Unable to soft unset built-in attributes in Asciidoctor

Reading from #72, I suppose that providing '!name' => '@' in attributes should soft unset a built-in attribute in Asciidoctor, but in fact the result is the same as a hard unset. The '-name' => '' syntax only stops this extension from passing an attribute to Asciidoctor. Using 'name' => false does a hard reset, too.

I guess the culprit is Middleman::AsciiDoc::AsciiDocExtension#merge_attributes, which seems to set the value of the hash to nil as long as the key starts or ends with a !. It also converts all falses to nils (Is there a reason to do this?).

Release version 1.0.0 (i.e., publish gem)

currently middleman-asciidoc is not available via rubygems.org.

Promote keywords and description attributes to page data

Promote the keywords and description attributes to page data. These are standard, reserved attribute names in AsciiDoc and there's no need to prefix them with page-. They are already understood to be page data.

Don't execute extension logic in config mode

When Middleman starts, it reads config.rb and runs all extensions two times. The first time through, it runs in config mode (app.mode? :config). The second time through it runs in either build or server mode (app.mode? :build or app.mode? :server, respectively). The config mode is intended to be used for registering cli flags. Since this extension doesn't currently contribute any cli flags, no processing is necessary in this mode. (In the future, if this extension does contribute cli flags, that logic would still be separate from normal processing).

In the constructor is called, return immediately in config mode. This will prevent the callbacks after_configuration and manipulate_resource_list from being called.

Is the directory indexes plugin supported?

I've got the directory indexes plugin enabled within my config.rb. How do I generate links in documents which are re-written to the directory_index format?

For example:

link:./setup/install{outfilesuffix}[Install]

Becomes:

<a href="./setup/install.html">Install</a>

Rather than:

<a href="./setup/install/">Install</a>
or
<a href="./setup/install/index.html">Install</a>

Pass all options from configuration when parsing AsciiDoc header

When parsing the AsciiDoc header, pass the full set of options defined in the :asciidoc key of the app configuration. This avoids any discrepancies between how the header and full document are parsed.

Asciidoc + Images with asset hashes

Hi guys,
is there a way to get asset hashing working with asciidoc files + Middleman?

Say I have an image in my .adoc like this:

image:mypic.png[mypic]

This won't get asset hashed at the moment. Any workarounds?

Thanks
marco

Set fixed local time for pages if time is set in app config

If the time is set in the app config:

set :time, Time.now

then set the localdate and localtime attributes on each AsciiDoc page accordingly. This allows all pages in the site to have a uniform concept of the time at which the build occurred.

This is similar to Jekyll's site.time variable (see https://jekyllrb.com/docs/variables/#site-variables).

Interpret page attributes values as YAML values

Interpret the value of page attributes as YAML values (by passing them through YAML.load). This ensures these attribute values are interpreted in the same way as they are when defined in the front matter.

For reference, see the Jekyll AsciiDoc plugin.

Run tests on Windows

Configure AppVeyor to run tests on Windows in a CI environment.

Provide a way to soft unset an AsciiDoc attribute value in the config

This integration sets several implicit attribute values, such as imagesdir. It should be possible to unset these attributes, either globally or per page, while still allowing the attribute to be set in the document. We'll call this a "soft" unset.

Promote multiple authors to page data

If multiple authors are specified in the document header, assign them as an array to the :authors key in the page data. If only a single author is specified, assign a single-element array containing that value to the :authors key.

Allow page layout to be set for AsciiDoc-based pages

Allow the page layout to be set for all pages processed by the AsciiDoc extension. In other words, it should be possible to apply a layout to AsciiDoc-based pages by defining a layout in the configuration settings for this extension.

activate :asciidoc, layout: :custom

Article date should respect application time zone

When the article date is parsed from the revdate AsciiDoc attribute, the date should default to the time zone set in Middleman (Time.zone) if a time zone is not specified.

Test integration with Asciidoctor Diagram

Since this extension sets the imagesoutdir attribute, it should also validate that the integration with Asciidoctor Diagram works as expected. Specifically, ensure that the cache is written to the correct folder and the images are generated to the correct folder. Document any information in the README the site author needs to know in order to successfully use Asciidoctor Diagram in a Middleman site.

Add tests for integration with middleman-blog

Add an integration test with middleman-blog to ensure that a post can be authored in AsciiDoc and that the post metadata is set correctly (title, author, date, tags, slug, etc).

Set :to_dir option on document when loading during conversion phase

When loading the document during the conversion/rendering phase (i.e., in the Tilt template), set the :to_dir option to the location where the file will be written (build_dir + dirname of destination_path).

opts[:to_dir] = ::File.expand_path \
    (::File.dirname ctx.current_page.destination_path),
    ctx.app.config[:build_dir]

Setting the :to_dir option on the document allows extensions (such as Asciidoctor Diagram) to know where the file will be output so it can write additional assets to that directory (or relative to it).

An alternate strategy is to add the outdir and outfile attributes to the attributes Hash. The benefit of this approach is that it also gives the content access to this information. We could also consider taking both approaches.

Generates HTML file without a file extension

Hi.
Just started using middleman and this plugin and it doesn't seem to be working anymore.
When you build the site (middleman site) the doc files are converted to html, but lack any sort of file extension. That results in the files not being served as HTML files, but plain-text files instead.

Support the use of custom templates

Support the use of custom Asciidoctor templates by providing an option in the activation to specify a set of template directories.

activate :asciidoc do |asciidoc|
  asciidoc.template_dirs = ['source/_templates']
end

The values of the :template_dirs option should be resolved to absolute paths. The option should then be passed on to the Asciidoctor processor. If the value is a String, it should first be coerced to an Array.

Add support for additional page layout options

Add the following permutations of page layout:

• _auto_layout - use the automatic layout; same as blank value
• false - don't apply a layout; create a standalone document
• ~ - don't apply a layout, but don't create a standalone document either

This change aligns the behavior of the Middleman extension with the Jekyll plugin. See https://github.com/asciidoctor/jekyll-asciidoc#specifying-a-layout

Change file extension

Is there a property to change the output from .html, to .xyz?
for different lang backed systems like java etc? ( .jsp / .gsp )

Automatically assign page-id attribute

Middleman uses the concept of a page ID to identify each page uniquely. This value should be passed down to the AsciiDoc document through the attribute page-id.

Rewrite file extension .adoc in relative links to .html

link:doc/linux.adoc[Linux] is converted to <a href="doc/linux.adoc">Linux</a>, but the actual target file is doc/linux.html, not doc/linux.adoc.

Add guide for contributing code

Add a guide that covers how to contribute code.

Method to promote custom AsciiDoc attributes to page data

Right now, attributes other than doctitle, author, authors, email, revdate, keywords, description can only become page data if they are prepend with page-. But it would be nice to have an extension option of additional attributes to promote to page data without the page- prefix. For example, writing page-tags attributes in a blog article feels weird because tags feel like properties of the article itself rather than properties of the generated webpage (unlike page-layout).

Extend xref macro to support referencing a page by page ID

Each resource in the sitemap of a Middleman site has a page ID, whether implicit or explicit. The page ID can be used to create a reference to a resource. In a template context, the url_for helper is used for this purpose. Extend the AsciiDoc xref macro to support create page references by page ID in an AsciiDoc document, effectively emulating the behavior of the url_for helper.

This extended behavior needs to be distinguished from a normal inter-document xref. This can either by done by:

a) requiring the page ID to be prefixed with /, or
b) requiring a normal inter-document xref to be prefixed with ./.

Here's an example of a page reference under proposal a).

xref:/about#[]

Here's an example of a page reference under proposal b)

xref:about#[]

Another idea is to require the extension, .adoc, to make a normal inter-document xref. This works since the page ID does not include the extension.

Assign implicit file info attributes per page

Assign the implicit file info attributes per page that would normally be set when invoking the AsciiDoc processor on the file. These attributes include the following:

• docfile - equivalent to resource.source_file
• docdir - the parent directory of resource.source_file
• docfilesuffix - the file extension of resource.source_file
• docname - the basename of resource.source_file minus file extension

We may also want to consider assigning the attributes regarding the document mtime, but these seem less important in the context of a site:

• docdate
• doctime
• docdatetime
• docyear

Convert attributes array to a hash in after_configuration

Convert the attributes array to a hash in after_configuration. This conversion makes it easier to check for and manipulate the attributes in the manipulate_resource_list method.

We might also consider switching the configuration to a hash instead of an array so that no conversion is necessary.

Either way, it's understood that the hash remains ordered as per normal Ruby rules.

Support the same AsciiDoc file extensions as Tilt

Middleman uses Tilt to convert the AsciiDoc files. This extension adds deeper integration. These two components should work on the same set of files.

Currently, this extension only considers AsciiDoc files that end in .adoc, while Tilt is configured to operate on .ad, .asciidoc, and .adoc files. This extension should use whatever AsciiDoc file extensions are registered with Tilt. That way, there's a central place to control which file extensions should be honored.

Set priority for resource list manipulator

To avoid problems with ordering when using other extensions such as middleman-blog, set the priority for the resource list manipulator. The priority should be greater than the priority of the built-in front matter extension (priority: 20) and less than the default priority for third-party extensions (priority: 50). A safe value to pick is 30.

Populate page metadata with page-related AsciiDoc attributes

It should be possible to populate page metadata, such as the page title, from page-related AsciiDoc attributes. Currently, these attributes are being passed as local variables.

Given the following input:

= Page Title
Author Name
2016-01-10
:page-tags: announcement, release

The following metadata should be assigned:

{ page: { title: 'Page Title', date: '2016-01-10', tags: 'announcement, release' } }

Note that any AsciiDoc attribute that begins with page- is converted into an entry in the page metadata after removing the page- prefix from the key.

Document features in README

Add documentation to README that explains the features provided by this extension and how to use them.

Features to cover include:

• Activating the extension and configuration Asciidoctor using extension options
  • alternate: configuring Asciidoctor using site-wide config
• Defining page-layout (and page-layout-engine) for a page. See #13 (comment)
• Defining page metadata using the AsciiDoc header. See #16 (comment)
• Defining base_dir
• Location of imagesdir (automatically assigned from Middleman config)
• How to write blog posts in AsciiDoc when using middleman-blog (probably better handled as a separate issue)