As slate is a Ruby application, it should be pretty trivial to support AsciiDoc via AsciiDoctor github.com/asciidoctor/asciidoctor. I'm sure @mojavelinux would be able to lend a hand.

Asides aren't very nicely styled when the document is printed.

When converting content from github markdown, I noticed that h4 h5 and h6 are not styled. I think they should all be treated as h3.

When new red carpet comes out, switch Git reference to a version number.

We can't use the current gem because of the ToC naming feature.

Upon scrolling up on OS X, the hash changes to #undefined, then it changes back to #introduction. I suggest we patch this such that it prevents the hash from even occuring if the hash is "undefined".

We're hosting static content, so we should be able to create the table of contents and <section>s before sending it to the user. This probably also involves removing Tocify.

Also #551 mentions preserving italics, which is a good idea.

Would be nice to have conditional Code annotations, e.g. explanatory words per-language.

Right now this feature is only useful if we can have text that makes sense for all language tab options. For example, the example below works because there's the same output format no matter which language option is chosen.

Get a Specific Kitten

require 'kittn'

api = Kittn::APIClient.authorize!('meowmeowmeow')
api.kittens.get(2)

import 'kittn'

api = Kittn.authorize('meowmeowmeow')
api.kittens.get(2)

curl "http://example.com/api/kittens/3"
-H "Authorization: meowmeowmeow"

The above command returns JSON structured like this:

{
 "id": 2,
 "name": "Isis",
 "breed": "unknown",
 "fluffiness": 5,
 "cuteness": 10
}

Would be nice to have code annotations specific to different code snippets as well. :)

Makes sense? Thanks!

• Remove function blah() {}, change to var blah = function() {}
• Remove trailing spaces
• Fix jslint violations

To link to the start of a document in a reliable way, anchor tags are added.

filename_anchor = %Q(<a anchor="#{File.basename(md)}"\n)

The / is stripped by middleman resulting in invalid HTML. Other tools such as Jekyll correctly render inline HTML. Is there a way to disable the HTML filtering?

Hey there. I noticed my code examples get pushed down really far when adding text. Can you give me a hint on how to correct this?

Hi!
Thank you for sharing this very useful code :)
Since our index.md is growing very fast, I am wondering if there is a way (or a hack) to split it in little and more manageable files.
So everyone in our team can edit the file that is responsible for, without problems with commits and merges.
I am thinking something like an option to write each TOC section in a separated file.

I really like the idea of hinting at which section of the docs best matches the search query.

Currently this is accomplished by re-ordering the TOC; however, this breaks the functionality of the TOC in that the content remains in its original order. Additionally, highlighting of the TOC headers breaks due to assumptions by the TOC code that order is maintained.

Potential solutions

• Some other indication of score
• raw solr score (0 - 100)

• of matches of the term within the section

• score color gradient, not sure of the visual design for that though. Perhaps small colored tabs to the right of each TOC heading.
• Indicate that the TOC has become a 'search result,' and just fix the TOC highlighting.

Thoughts?

Hi,

Here's an issue I ran across. I am working on Project Euler problems, and want to use Slate to display solutions in clojure, haskell, python, and ocaml. The language tabs work as expected until I add ocaml to language_tabs. The problem is that the ocaml solution is presented on every tab.

By dint of experiment I found that lying (say by claim the ocaml solution is in perl or ruby) fixes the apparent problem at the cost of using the wrong syntax highlighter. For what its worth, the Rouge demo page at http://rouge.jayferd.us/demo suggests that ocaml should be a supported language.

Here is a short index.md file that reproduces the issue:
https://gist.github.com/drcabana/8391936

I think Slate is very nice; thank you for sharing your work.

yours,
David Cabana

Below I will attach a short index.md file that illustrates the problem.

With large websites, the flicker from the initial load is apparent.

http://www.screencast.com/t/XIBbZ7ORlj

I'm seeing some strange behavior with null Is this expected?

<div name="null3" data-unique="null3"></div>

http://bootstraponline.github.io/api-docs/#null3

<ul id="tocify-header1" class="tocify-header">
<li class="tocify-item tocify-focus" data-unique="appium-server-capabilities"><a>Appium server capabilities</a></li>

<ul class="tocify-subheader" data-tag="2" style="display: block;">
<li class="tocify-item" data-unique="null3"><a></a></li>
<li class="tocify-item" data-unique="null4"><a></a></li>
</ul>

</ul>

My guess is that the h4 headings are causing problems.

My slate app keeps on shutting down after some hours with this message, do you know what could it be?

C:\slate>rake build
cd C:/slate
bundle exec middleman build --clean
identical build/images/logo.png
identical build/fonts/icomoon.svg
identical build/fonts/icomoon.woff
identical build/fonts/icomoon.ttf
identical build/fonts/icomoon.eot
error build/javascripts/lang_selector.js
error build/javascripts/jquery.tocify.js
error build/javascripts/all.js
error build/javascripts/jquery_ui.js
identical build/stylesheets/variables.css
identical build/stylesheets/syntax.css
identical build/stylesheets/icon-font.css
identical build/stylesheets/normalize.css
identical build/stylesheets/screen.css
identical build/stylesheets/print.css
identical build/stylesheets/screen.css.scss.bak
identical build/index - Copy.html
identical build/index.html
There were errors during this build, re-run with middleman build --verbose to see the full exception.
rake aborted!
Command failed with status (1): [bundle exec middleman build --clean...]

Tasks: TOP => build
(See full trace by running task with --trace)

I have cloned your repo and used objc instead of python. That's the only change I did. Here is my fork: https://github.com/funkyboy/slate
My changes: https://github.com/funkyboy/slate/commit/d19f7ba7fc6f0d11a049548298f5a5b8d0d35c63
Regardless of the tab selected on the top right, the objc code never hides.
Any hint?

Not being very familiar with Middleman or Ruby, I was wondering why live reload wasn't working out of the box. Simple fix, just add this to config.rb:

activate :livereload

Not really a bug, but might want to mention it in the read me.

This is a great tool, thank you so much for creating it!

On a large slate site, it's a pain to reload the entire page when quickly looking through all the languages for a single example.

diff --git a/source/javascripts/lang_selector.js b/source/javascripts/lang_selector.js
index 4e3dbc9..8ef5604 100644
--- a/source/javascripts/lang_selector.js
+++ b/source/javascripts/lang_selector.js
@@ -43,10 +43,10 @@ function setupLanguages(l) {
     activateLanguage(languages[0]);
   }

-  // if we click on a language tab, reload the page with that language in the URL
+  // if we click on a language tab, activate that language
   $("#lang-selector a").bind("click", function() {
-    window.location.replace("?" + $(this).data("language-name") + window.location.hash);
+    // do not reload the page every time the language is changed
+    activateLanguage($(this).data("language-name"));
     return false;
   });
-
-}
+}

We are thinking of using slate, but would like to simply increase the width of the middle pane, and reduce of the width of the far right pane (language specific examples). Is this possible with a simple config change?

"Introduction" in ToC of the the screenshot above should be highlighted in blue, since that's the current scroll position.

Clicking on credits is activating the menu button two above it. Also direct links to credits sometimes fail.

• Screencast

This project looks awesome!

I think assuming that it's "language_tabs" rather than libraries/implementations or whatever implies that there could be more than one sample in a given language is a limitation, though.

One common example: it's not unusual to have a both a Ruby-on-Rails and pure Ruby library. Another example (though both can be integrated with Ruby) is comparing Mongoid vs MongoMapper (both Ruby).

https://wiki.openstack.org/wiki/SDKs#OpenStack_Toolkits and http://redis.io/clients also show many examples of multiple libraries in the same language. It's unlikely you would want to document all of those, but it is pretty reasonable to show the a few popular Python SDKs for OpenStack (e.g. pyrax vs Apache libcloud).

Just bundle install'ed on a fresh machine and got the following error:

root@646c40a92fe9:/api-docs# bundle exec middleman server
/usr/local/rvm/gems/ruby-2.0.0-p353/gems/execjs-1.4.0/lib/execjs/runtimes.rb:51:in `autodetect': Could not find a JavaScript runtime. See https://github.com/sstephenson/execjs for a list of available runtimes. (ExecJS::RuntimeUnavailable)

Added this to the Gemfile:

gem 'execjs'
gem 'therubyracer', :platforms => :ruby

and things worked very well. Isn't it a missing dependency?

Very long pages sometimes lag, which should be minimized if possible.

Hey, this is not an issue, it's fan mail. I have been using Slate to do some work which involves comparing source code in several languages. I have been very happy with the result. If you want to see some Slate in the wild, check out http://drcabana.github.io/build-a-quine/#introduction

I have a similar but much longer project in progress, wherein I plan to show detailed solutions to the first 33 Project Euler problems in Haskell, F#, Python, and Clojure. I hope it will be useful to people trying to learn a bit about functional programming. Slate is the bomb for this sort of work. Thank you for sharing it.

See list item 3 from https://github.com/tripit/slate/wiki/Deploying-Slate/99cd095c465af1d1674ea6d49fa525e7afd8de43.

Reword if you'd like.

It happens if there is no URL in the header, and the user clicks on a ToC item.

Currently, slate automatically creates anchors from the header name, so that, for example
### Response

becomes

<h3 id="response">Response</h3>

and you can refer to the corresponding paragraph right in the text. That's very useful.

The problem is if there are more than one 'Response' paragraphs within the doc, you cannot tell one header from another when creating an internal link.

It would be great to have ability to set a custom ID for anchor in slate syntax.

Thanks!

Issue pointed out by @bootstraponline in #43, we should skip to the first result, not just filter the sections down.

I deployed dev rev 7386fd to gh-pages. If I search for write docs, it doesn't find the match. Are the h1s not indexed?

When deploying the API documentation into a custom deployment, it may be feasible that such a deployment may require query parameters in order to properly serve the content.

Unfortunately, the language selector currently assumes that no other query parameters exist, aside from the language identifier, and simply overwrites any existing query parameters when a new language is selected from the tab.

This can be fixed with the following changes:

When updating the location on a click event, prepend the language identifier to the existing query if the first query has an equals sign ('='), otherwise replace only the first query parameter with the new language identifier.

When searching for a language in the query, split the query by parameter and check the first parameter for a language match.

This method would at least preserve all existing query parameters that follow the usual query=value format, which would likely be sufficient for most use cases.

Hi,

I would like to vertically align blocks of code with h4 headers.
I've added h4 to the list of selectors in layout.erb, it works but now they appear in the table of content.

Is it possible to remove h4 from TOC but still keep the code blocks aligned?

On the appium docs if you search for m the following exception is raised:

Uncaught Error: Syntax error, unrecognized expression: .tocify-item[data-unique=migrating-your-tests-from-appium-0.18.x-to-appium-1.x]

<h1 id="migrating-your-tests-from-appium-0.18.x-to-appium-1.x"><span id="migrating-to-1-0.md"></span>Migrating your tests from Appium 0.18.x to Appium 1.x</h1>

The id generated by slate fails to filter out special characters that interfere with css selectors.

I did the few steps to install and use slate but after launching middleman server, when I am trying to access to localhost:4567, the application crashes with the following error:

== The Middleman is loading
== The Middleman is standing watch at http://0.0.0.0:4567
== Inspect your site configuration at http://0.0.0.0:4567/__middleman/
/Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/tilt-1.4.1/lib/tilt/markdown.rb:125: [BUG] Segmentation fault
ruby 2.0.0p247 (2013-06-27 revision 41674) [x86_64-darwin12.3.0]

-- Crash Report log information --------------------------------------------
See Crash Report log file under the one of following:
* ~/Library/Logs/CrashReporter
* /Library/Logs/CrashReporter
* ~/Library/Logs/DiagnosticReports
* /Library/Logs/DiagnosticReports
the more detail of.

-- Control frame information -----------------------------------------------
c:0030 p:---- s:0201 e:000200 CFUNC :render
c:0029 p:0026 s:0197 e:000196 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/tilt-1.4.1/lib/tilt/markdown.rb:125
c:0028 p:0034 s:0191 e:000190 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/tilt-1.4.1/lib/tilt/template.rb:103
c:0027 p:0252 s:0185 E:000310 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/core_extensions/rendering.r
c:0026 p:0171 s:0167 e:000166 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/core_extensions/rendering.r
c:0025 p:0217 s:0154 e:000153 BLOCK /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/sitemap/resource.rb:143
c:0024 p:0043 s:0150 e:000149 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/activesupport-3.2.16/lib/active_support/notifications.rb:125
c:0023 p:0054 s:0145 e:000144 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/util.rb:42
c:0022 p:0021 s:0138 e:000137 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/application.rb:215
c:0021 p:0015 s:0133 e:000132 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/sitemap/resource.rb:16
c:0020 p:0067 s:0128 E:000888 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/sitemap/resource.rb:114
c:0019 p:0181 s:0121 E:000230 METHOD /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/core_extensions/request.rb:
c:0018 p:0013 s:0109 e:000108 BLOCK /Users/Stephanie/.rvm/gems/ruby-2.0.0-p247@clm-api-doc/gems/middleman-core-3.2.2/lib/middleman-core/core_extensions/request.rb: [FINISH]
c:0017 p:---- s:0107 e:000106 CFUNC :catch
......

These are the gems installed:
Installing rake (10.1.1)
Installing i18n (0.6.9)
Installing multi_json (1.8.4)
Installing activesupport (3.2.16)
Using bundler (1.5.3)
Installing chunky_png (1.2.9)
Installing coffee-script-source (1.7.0)
Installing execjs (1.4.0)
Installing coffee-script (2.2.0)
Installing fssm (0.2.10)
Installing sass (3.2.14)
Installing compass (0.12.2)
Installing eventmachine (1.0.3)
Installing http_parser.rb (0.5.3)
Installing em-websocket (0.5.0)
Installing ffi (1.9.3)
Installing tilt (1.4.1)
Installing haml (4.0.5)
Installing hike (1.2.3)
Installing json (1.8.1)
Installing kramdown (1.3.1)
Installing rb-fsevent (0.9.4)
Installing rb-inotify (0.9.3)
Installing rb-kqueue (0.2.0)
Installing listen (1.3.1)
Installing rack (1.5.2)
Installing rack-test (0.6.2)
Installing thor (0.18.1)
Installing middleman-core (3.2.2)
Installing sprockets (2.10.1)
Installing sprockets-helpers (1.0.1)
Installing sprockets-sass (1.0.2)
Installing middleman-sprockets (3.2.0)
Installing uglifier (2.4.0)
Installing middleman (3.2.2)
Installing middleman-gh-pages (0.0.3)
Installing rack-livereload (0.3.15)
Installing middleman-livereload (3.1.1)
Installing rouge (1.3.2)
Installing middleman-syntax (2.0.0)
Using redcarpet (3.0.0) from https://github.com/vmg/redcarpet.git (at master)
Your bundle is complete!

I am using ruby-2.0.0-p247.

Please advise on what I did wrong in order to make it works.
Thanks for your help

Make Slate's design responsive so it works on mobile devices.

When a request is made, HTTP query parameters get sent to the server, hash/fragment values don't. If we remove the query parameter it would probably greatly improve load time.

The URL could look something like:
example.com#ruby@making-requests

ruby is the language and making-requests is the id.

It'd be useful to have a way to toggle explanatory text in the center column when the code examples change. If someone has Ruby selected for language examples, they probably aren't interested in reading the explanation in the center for every language.

Hey! I added a page on using includes to the wiki. I'm putting this issue here to call attention to it for reviewal, etc. If you'd like to reject the writing, feel free to delete the page from the wiki and its link from the homepage.

Hi - I just went to build slate with rake build. Deployed the files statically on our server, which is https-only.

jQuery was then blocked because it is requesting it on http:// instead of generic //:

[blocked] The page at 'https://www.priceplow.com/api/documentation/index.html' was loaded over HTTPS, but ran insecure content from 'http://code.jquery.com/jquery-1.10.1.min.js': this content should also be loaded over HTTPS.

I'll see if there's a way to specify this in the build options, but it should probably just use // instead of http://

Thanks! This stuff looks killer!
Mike

Kindly provide the tag for version maintenance.

Currently the left nav bar is never scrolled.

Uncaught Error: Syntax error, unrecognized expression: .highlight.c# jquery-1.10.1.js:1924

language_tabs:
  - c#

It'd be nice to have a way to specify a multi-line code block that stays in the center column.

A little x in the search box to clear the search would be nice.

I got issue to put android API into the doc due to it's formatting same as java, how to support it?

v1.9.0 is on GitHub

Hi, I'm running into an error while trying to build slate. Is anyone else running into this?

I had found an article to run:

sudo ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future gem install eventmachine

which worked previously, but it seems to be breaking again for me.

ASROACH-M-N05D:slate ashleyroach$ bundle install
Fetching gem metadata from http://rubygems.org/.......
Fetching additional metadata from http://rubygems.org/..
Installing rake (10.2.2)
Installing i18n (0.6.9)
Installing minitest (4.7.5)
Installing multi_json (1.9.2)
Installing thread_safe (0.3.3)
Installing tzinfo (0.3.39)
Installing activesupport (4.0.4)
Installing chunky_png (1.3.0)
Installing coffee-script-source (1.7.0)
Installing execjs (2.0.2)
Installing coffee-script (2.2.0)
Installing fssm (0.2.10)
Installing sass (3.2.19)
Installing compass (0.12.5)
Installing compass-import-once (1.0.4)

Gem::Installer::ExtensionBuildError: ERROR: Failed to build gem native extension.

/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/ruby extconf.rb 

checking for main() in -lssl... yes
checking for main() in -lcrypto... yes
checking for openssl/ssl.h... yes
checking for openssl/err.h... yes
checking for rb_trap_immediate in ruby.h,rubysig.h... no
checking for rb_thread_blocking_region()... yes
checking for inotify_init() in sys/inotify.h... no
checking for __NR_inotify_init in sys/syscall.h... no
checking for writev() in sys/uio.h... yes
checking for rb_wait_for_single_fd()... yes
checking for rb_enable_interrupt()... no
checking for rb_time_new()... yes
checking for sys/event.h... yes
checking for sys/queue.h... yes
creating Makefile

make "DESTDIR="
compiling binder.cpp
compiling cmain.cpp
compiling ed.cpp
compiling em.cpp
compiling kb.cpp
compiling page.cpp
compiling pipe.cpp
compiling rubymain.cpp
rubymain.cpp:330:17: warning: 'BIO_s_mem' is deprecated: first deprecated in OS X 10.7 [-Wdeprecated-declarations]
out = BIO_new(BIO_s_mem());
^
/usr/include/openssl/bio.h:626:13: note: 'BIO_s_mem' declared here
BIO_METHOD *BIO_s_mem(void) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;

63 warnings generated.
linking shared-object rubyeventmachine.bundle
clang: error: unknown argument: '-multiply_definedsuppress' [-Wunused-command-line-argument-hard-error-in-future]
clang: note: this will be a hard error (cannot be downgraded to a warning) in the future
make: *** [rubyeventmachine.bundle] Error 1

/snipped lots of warnings

Gem files will remain installed in /Users/ashleyroach/Documents/Source/slate/vendor/bundle/gems/eventmachine-1.0.3 for inspection.
Results logged to /Users/ashleyroach/Documents/Source/slate/vendor/bundle/gems/eventmachine-1.0.3/ext/gem_make.out
An error occurred while installing eventmachine (1.0.3), and Bundler cannot continue.
Make sure that gem install eventmachine -v '1.0.3' succeeds before bundling.