• GNU Emacs 24.2.1 (Gentoo package: app-editors/emacs-23)
• org-mode version 7.9.3d (package.el: org 20130114) or,

• GNU Emacs 24.2 (from here)
• org-mode version 7.9.1 (package.el: org 201209003)
• Gentoo Linux: GNU Emacs 23.2.1, org-mode version 7.9.3d
• MacOSX (darwin) 10.8.2:

To help generating top-level page index, jekyll-org provides toplink block. toplink block will uses the list of page IDs, evaulating the contents in the block multiple times according to the number of elements in topnav-list of the _config.yml as in the following:

topnav-list: [ "home", "article", "pg1", "pg2" ]

toplink tag accepts five parameters separated by comma('=,=') character. For example:

{% toplink id, label, locale, url, self %}
  ...
{% endtoplink %}

Each parameter name will turn to the variable name which can be used in the toplink block. The meaning of the variables are:

• 1st parameter (id): id of the page; this is the analogous to the each element in topnav-list.
• 2nd parameter (label): label of the page; which can be used as the short name of the page.
• 3rd parameter (locale): mnemonic of the page locale such as 'en' for English, 'ko' for Korean. If the locale of the evaluating page is the same as the current page, this will be an empty string (=""=).
• 4th parameter (url): URL of the page
• 5th parameter (self): true if the current page is the same as the evaluating page.

For example, if you want to create hyperlinks to the top-level pages, you can do this by:

<ul>
{% toplink id, label, locale, url, self %}
  <li><a href="{{url}}">{{label}}</a></li>
{% endtoplink %}
</ul>

If you want to remove the hyperlink for the current page, among evaluating pages, you can check the 5th parameter as in the following:

<ul>
{% toplink id, label, locale, url, self %}
  {% if self == true %}
  <li>{{label}}</li>
  {% else %}
  <li><a href="{{url}}">{{label}}</a></li>
  {% endif %}
{% endtoplink %}
</ul>

articles block can enumerate pages which has a specified layouts.

articles block will be evaluated multiple times for each article. The usage is almost the same as toplink block.

articles will accept four parameters, and each meaning of the parameter is:

• 1st parameter (layouts): a name of the variable in _config.yml where its value is a list of layout names.
• 2nd parameter (id): id of the article page
• 3rd parameter (title): title of the article page.
• 4th parameter (lead): short description of the article page.
• 5th parameter (url): URL of the article page
• 6th parameter (lang): name of the locale of the article page. (such as "English" or "Korean") If the locale of the current page is the same as the evaluating article page, this will be an empty string (=""=).

For example, suppose that you have pages in either "my_article1" layout or "my_article2" layout. To enumerate these pages, you need to specify the list of layouts in _config.yml like:

article_layouts: [ "my_article1", "my_article2" ]

Then, you can enumerate these pages with article block like:

<ul>
  {% articles article_layouts, id, title, lead, url, lang %}
    {% if lang == "" %}
  <li><a href="{{url}}">{{title}}</a></li>
    {% else %}
  <li><a href="{{url}}">{{title}}</a> ({{lang}}) </li>
    {% endif %}
  {% endarticles %}
</ul>

Or, if you want to insert 'lead' value, use the following:

<ul>
  {% articles article_layouts, id, title, lead, url, lang %}
    {% if lead == nil or lead == "" %}
      {% assign leadsep = '' %}
    {% else %} 
      {% assign leadsep = ': ' %}
    {% endif %}

    {% if lang == "" %}
  <li><a href="{{url}}">{{title}}</a>{{leadsep}}{{lead}}</li>
    {% else %}
  <li><a href="{{url}}">{{title}}</a> ({{lang}}){{leadsep}}{{lead}}</li>
    {% endif %}
  {% endarticles %}
</ul>

You may have some problem on the generated table of contents, which looks like following:

The problem is that, your Emacs scripts set org-odd-levels-only to t, but the batch script, publish.el in the package, does not aware of it. To work around this, add "odd" in the STARTUP keyword.

#+STARTUP: odd

Your Emacs uses out-dated org-version probably 6.x. Install recent org-mode.

However, there are some problems with this approach.

In scaffolding page, one of the left-side navigation item is highlighted, depending on the current location of the contents.

I cannot make this happen on org-generated page, since the contents generation is handled by org-mode, which I cannot control manually.

In detail, the scaffolding has following structures:

<!-- This is the left-side navigation list -->
<div class="span3 bs-docs-sidebar">
  <ul class="nav nav-list bs-docs-sidenav">
    <li><a href="#sec-1"><i class="icon-chevron-right"></i>Section 1</a></li>
    <li><a href="#sec-2"><i class="icon-chevron-right"></i>Section 2</a></li>
    <li><a href="#sec-3"><i class="icon-chevron-right"></i>Section 3</a></li>
    ...
  </ul>
</div>

<!-- This is the right-side, contents -->
<div class="span9">
  <section id="sec-1">
    <div class="page-header">
      <h1>Section 1</h1>
    </div>
    <p>...</p>
  </section>

  <section id="sec-2">
    <div class="page-header">
      <h1>Section 2</h1>
    </div>
    <p>...</p>
  </section>

  ...
</div>

Following is the structure that I implemented:

<!-- This is the left-side navigation list -->
<div class="span3 bs-docs-sidebar">
  <ul class="nav nav-list bs-docs-sidenav">
    <li><a href="#sec-1"><i class="icon-chevron-right"></i>Section 1</a></li>
    <li><a href="#sec-2"><i class="icon-chevron-right"></i>Section 2</a></li>
    <li><a href="#sec-3"><i class="icon-chevron-right"></i>Section 3</a></li>
    ...
  </ul>
</div>

<!-- This is the right-side, contents -->
<div class="span9">
  <!-- from now on, this is org-mode generated contents -->
  <div id="outline-container-1" class="outline-2">
    <h2 id="sec-1">Section 1</h2>
    ...
  </div>

  <div id="outline-container-2" class="outline-2">
    <h2 id="sec-1">Section 2</h2>
    ...
  </div>
  ...
</div>

1. Since the body content itself is generated by org-mode, I cannot make the highlighting feature of the navigation bar (in the left side of the page).

jekyll-org