danielgtaylor / aglio Goto Github PK

View Code? Open in Web Editor NEW

4.7K 4.7K 481.0 798 KB

An API Blueprint renderer with theme support that outputs static HTML

CoffeeScript 78.81% JavaScript 0.40% HTML 0.49% API Blueprint 19.97% Dockerfile 0.33%

aglio's Introduction

Hi , I'm Daniel

A software engineer tech lead at iStreamPlanet in Seattle, WA

I'm passionate about 🎬 live video streaming, 🛠 HTTP & REST APIs and developer tooling like 📦 SDKs & 🖥 CLIs

aglio's People

Stargazers

Watchers

Forkers

bawerd fancyremarker petebrowne unquietcode svenmueller assembledadam david-thorman pmotch billiam dberesford jhankim profburial midrissi shanejonas codable aleub jeromebenois klevak jvonniedapn rschutt kukat agurha alvarlaigna mikaa123 scase rexk spect porubsky sergiocruz mojocakes noteon circuitbomb jonabyrnes chesleybrown arbus rezanachmad vaseker eddieroger xus hhhonzik victorcastelan mgesmundo joshma leandrostoroli ets ryanzhou polastre worldspawn bartocc aichholzer zurborg kayhadrin ribot lucccx stephenemslie dulanism schellkenig erdeepaksharma nickpresta prolificinteractive alachaum juans-zz ajcstriker diablofong nobodysnightmare seemsindie tout achretien fivetanley matyunin leutrimhusaj cyriltovena keevol sharonknight gerardobort davidonlaptop mjgp2 besttests protossoario ebuynow jolleon tunming manuyavuz wennergr mackjoner codeorganic maximeaubaret marcosrioj linusu hfucek alexturek jewelsjacobs niasand hcf waynehuangplus shyblue riturajinw a7tech sibrus jacko972

aglio's Issues

Installation hangs on GET component/emitter

The github repository directory it is looking for doesn't exist anymore...

sudo npm install -g aglio
Password:
npm http GET https://registry.npmjs.org/aglio
npm http 304 https://registry.npmjs.org/aglio
npm http GET https://registry.npmjs.org/chokidar
npm http GET https://registry.npmjs.org/coffee-script
npm http GET https://registry.npmjs.org/cli-color
npm http GET https://registry.npmjs.org/highlight.js
npm http GET https://registry.npmjs.org/marked
npm http GET https://registry.npmjs.org/jade
npm http GET https://registry.npmjs.org/moment
npm http GET https://registry.npmjs.org/protagonist
npm http GET https://registry.npmjs.org/socket.io
npm http GET https://registry.npmjs.org/yargs
npm http GET https://registry.npmjs.org/stylus
npm http 304 https://registry.npmjs.org/cli-color
npm http 304 https://registry.npmjs.org/chokidar
npm http 304 https://registry.npmjs.org/coffee-script
npm http 304 https://registry.npmjs.org/jade
npm http 304 https://registry.npmjs.org/moment
npm http 304 https://registry.npmjs.org/socket.io
npm http 304 https://registry.npmjs.org/yargs
npm http 304 https://registry.npmjs.org/marked
npm http 304 https://registry.npmjs.org/stylus
npm http 304 https://registry.npmjs.org/highlight.js
npm http 304 https://registry.npmjs.org/protagonist
npm http GET https://registry.npmjs.org/recursive-readdir/0.0.2
npm http GET https://registry.npmjs.org/fsevents
npm http 304 https://registry.npmjs.org/recursive-readdir/0.0.2
npm http 304 https://registry.npmjs.org/fsevents
npm http GET https://registry.npmjs.org/has-binary-data/0.1.3
npm http GET https://registry.npmjs.org/socket.io-client/1.1.0
npm http GET https://registry.npmjs.org/debug/0.7.4
npm http GET https://registry.npmjs.org/socket.io-adapter/0.2.0
npm http GET https://registry.npmjs.org/engine.io/1.4.0
npm http GET https://registry.npmjs.org/socket.io-parser/2.2.1
npm http 304 https://registry.npmjs.org/socket.io-client/1.1.0
npm http 304 https://registry.npmjs.org/debug/0.7.4
npm http GET https://registry.npmjs.org/d
npm http GET https://registry.npmjs.org/memoizee
npm http GET https://registry.npmjs.org/timers-ext
npm http GET https://registry.npmjs.org/es5-ext
npm http 304 https://registry.npmjs.org/engine.io/1.4.0
npm http 304 https://registry.npmjs.org/memoizee
npm http 304 https://registry.npmjs.org/timers-ext
npm http 304 https://registry.npmjs.org/has-binary-data/0.1.3
npm http 304 https://registry.npmjs.org/d
npm http 304 https://registry.npmjs.org/es5-ext
npm http GET https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.4.tgz
npm http 200 https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.4.tgz
npm http 304 https://registry.npmjs.org/socket.io-parser/2.2.1
npm http 304 https://registry.npmjs.org/socket.io-adapter/0.2.0
npm http GET https://registry.npmjs.org/socket.io-parser/2.1.2
npm http 304 https://registry.npmjs.org/socket.io-parser/2.1.2
npm http GET https://registry.npmjs.org/component-emitter/1.1.2
npm http GET https://registry.npmjs.org/isarray/0.0.1
npm http GET https://registry.npmjs.org/benchmark/1.0.0
npm http GET https://registry.npmjs.org/json3/3.2.6
npm http 304 https://registry.npmjs.org/isarray/0.0.1
npm http 304 https://registry.npmjs.org/component-emitter/1.1.2
npm http 304 https://registry.npmjs.org/benchmark/1.0.0
npm http GET https://registry.npmjs.org/benchmark/-/benchmark-1.0.0.tgz
npm http GET https://registry.npmjs.org/base64id/0.1.0
npm http GET https://registry.npmjs.org/engine.io-parser/1.1.0
npm http GET https://registry.npmjs.org/debug/1.0.3
npm http GET https://registry.npmjs.org/ws/0.4.31
npm http GET http://github.com/component/emitter/archive/1.0.1.tar.gz

Support %-escaped values in URI parameters description

If a parameter list starts with something containing %-escaped values, the parameter list does not show up in the html output - e.g. this will hide the parameter list completely:

+ Parameters

    + geo%5Blatitude%5D (float, required, `51.246074`) ... Geo Search Latitude
    + locale (string, optional, `US`) ... Local code to use

If one or more items containing %-escaped values occur later in the list, they are just omitted - e.g.: this will render a parameter section with only locale shown:

+ Parameters

    + locale (string, optional, `US`) ... Local code to use
    + geo%5Blatitude%5D (float, required, `51.246074`) ... Geo Search Latitude

API Blueprint itself supports %-escaped values by now:
apiaryio/snowcrash#107

Server preview doesn't work when trying to access from another machine

Scenario:

I'm on a linux server in the cloud (AWS, Rackspace, etc); no firewall, no "security groups" blocking anything inbound or outbound. The aglio rendered HTML is served through Nginx.
I run Aglio on the linux server with server preview (e.g. aglio -i example.md --server)
On another machine I try to access the preview server (e.g. 1.2.3.4:3000) and it doesn't work (server not found -- tried curl, wget, Chrome -- also, nmap says port 3000 is closed).

If I'm on the local machine, I can hit it with curl (localhost:3000) and it comes back just fine. Nmap says port 3000 is open.

Not sure if this is expected behavior or not (perhaps you don't actually want it to be accessible to the outside). If it's not, then perhaps it's only binding to localhost or something like that. I didn't do much troubleshooting beyond this. If it helps that I get some logs of some type to you, let me know. I can provide more details.

Windows Errors & Crashes

Hello Daniel,

I'm trying to use your project for pretty printing our Blueprint API specs. In the head of master I'm getting the following error:

c:\dev\3dparty\aglio>aglio -i example.md -o output.html
{ code: 2,
message: 'unexpected list block, expected a group, resource or an action definition, e.g. '# Group ', '# []' or '# '',
location: [] }

Error during install on OS X Mavericks

As it's trying to install Snowcrash, it ends up with the following errors that completely crash the installation and I'm not sure how to get around it. Any help would be awesome.

CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/snowcrash.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/posix/RegexMatch.o
  LIBTOOL-STATIC Release/snowcrash.a
libtool: unrecognized option `-static'
libtool: Try `libtool --help' for more information.
make: *** [Release/snowcrash.a] Error 1
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/Users/Lonnie/.nvm/v0.8.25/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:267:23)
gyp ERR! stack     at ChildProcess.EventEmitter.emit (events.js:99:17)
gyp ERR! stack     at Process._handle.onexit (child_process.js:686:10)
gyp ERR! System Darwin 13.0.0
gyp ERR! command "node" "/Users/Lonnie/.nvm/v0.8.25/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /Users/Lonnie/.nvm/v0.8.25/lib/node_modules/aglio/node_modules/protagonist
gyp ERR! node -v v0.8.25
gyp ERR! node-gyp -v v0.10.0
gyp ERR! not ok 
npm ERR! weird error 1
npm ERR! not ok code 0

Multiline header support (upstream)

When you define an endpoint, then add headers for an example request, if you have Authorization headers, the parser will skip them unless they are on one line (which looks poorly formatted)

For example,

Content-Type: application/x-www-form-urlencoded
Authorization:
    OAuth oauth_consumer_key="your_consumer_key",
    oauth_nonce="random_string_or_timestamp",
    oauth_token="oauth_token_received_from_step_2"
    oauth_signature="your_consumer_secret",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="current_timestamp",
    oauth_verifier="users_verifier"

My guess is that the parser looks for a key: value pair separated by a colon, and since there's nothing after the colon on the Authorization: line and no colons on the following lines, it just skips over all of those lines.

LiveReload?

Is live reload functionality for the web server on the timeline?
It would be great if the webpage auto refreshed what the page was regenerated.

PS - This is fantastic guys, much love.

Parameter name shown as 0, 1, 2, ...

I am using the API blueprint preview (v0.2.2) in the Atom editor (v0.136.0) and I have used the following API description for a GET call:

## GET /v1/campaigns{?ids,name}

+ Parameters

  + ids (array, optional) ... List of ids for which the campaigns are returned.
  + name (string, optional) ... A filter for the campaign name.

What I get in the preview window is the following.

0 array (optional) 
List of ids for which the campaigns are returned.

1 string (optional) 
A filter for the campaign name.

So, instead of the parameter names "ids" and "name", I get 0 and 1. Can you help me what is wrong?

Same links for all resources within a group

Hello,

We started using Aglio yesterday, and we noted that all resources within a group have the same link, including its target's ids. For example, considering this input:

Group Foobar
============

...

GET /resources/
--------------

...

+ Response 200 (application/json)

        ...


GET /resources/?limit={page_limit}
---------------------------------

...

+ Response 200 (application/json)

        ...


GET /resource/{id}/
------------------

...

+ Response 200 (application/json)

        ...

Aglio generates:

<!-- SIDEBAR -->
<div class="list-group">
    <a href="#foobar" class="list-group-item heading">Foobar</a>
    <a href="#foobar-" class="list-group-item">
        <i class="fa fa-arrow-circle-down"></i>&nbsp;GET /resources/
    </a>
    <a href="#foobar-" class="list-group-item">
        <i class="fa fa-arrow-circle-down"></i>&nbsp;GET /resources/?limit={page_limit}
    </a>
    <a href="#foobar-" class="list-group-item">
        <i class="fa fa-arrow-circle-down"></i>&nbsp;GET /resource/{id}/
    </a>
</div>

<!-- MAIN -->
<h4 id="foobar-">
    Foobar&nbsp;
    <a href="#foobar-"><i class="fa fa-link"></i></a>
</h4>

<!-- all resources have this same id -->
<section id="foobar--get" class="panel panel-info">

I didn't read the source code, but it seems like a bug on group rendering. If it's confirmed it is a bug, I can make a fork and work on it.

CLI: exit process with correct error code

The CLI tool just logs errors and warnings to stderr and exits the process as normal with exit code 0.

If you use some CI tool like jenkins, your build will be marked as successful.
The output on jenkins looks like this:

> aglio -i api.md -o build/api/index.html
>> Line 101: undefined symbol 'foo' (error code 3)
Finished: SUCCESS

Examples broken due to malformed links

The examples listed under the Example Output section do not display correctly through htmlpreview.github.io.

Need to link to the raw content instead of the file itself

run command error -> aglio -i template_out.md -o template.html

~$ aglio -i template_out.md -o template.html

{"errno":34,"code":"ENOENT","path":"template_out.md"}

What is this errno mean?
Is it template_out.md error or aglio bug?

Update default theme to use GitHub Markdown CSS

Since some of the markdown styles can get a little whacky, it would be nice if there was a clean template style using the GitHub Markdown CSS from the project: https://github.com/sindresorhus/github-markdown-css.

Navigation layout is broken for long endpoints

Try rendering this blueprint:

FORMAT: 1A

# Group Book Service

## GET /book/{id}/chapter/{number}/paragraphs
Returns paragraphs of the specified chapter of the book

Here is what you'll get:

It gets worse with more endpoints.

Bug using example.md file

Hello,
Using the example markdown provided https://raw.github.com/danielgtaylor/aglio/master/example.md and a default global aglio installation, I get this error:

aglio -i blueprint.md -o doc.html
>> Line 34: resource model can be specified only for a named resource, name your resource, e.g. '# <resource name> []' (error code 3)

Am i doing something wrong, or is the example not valid anymore?

OS X installation failed at the [email protected] install script

Hello!

I can not install aglio on OS X 10.9.4.

sudo npm install -g aglio output:

> [email protected] install /usr/local/lib/node_modules/aglio/node_modules/protagonist
> node-gyp rebuild

  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/HTTP.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/MarkdownBlock.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/MarkdownParser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/Parser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/ParserCore.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/Serialize.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/SerializeJSON.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/SerializeYAML.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/UriTemplateParser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/snowcrash.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/csnowcrash.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/CBlueprint.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/CSourceAnnotation.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/posix/RegexMatch.o
  LIBTOOL-STATIC Release/snowcrash.a
libtool: unrecognized option `-static'
libtool: Try `libtool --help' for more information.
make: *** [Release/snowcrash.a] Error 1
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:267:23)
gyp ERR! stack     at ChildProcess.emit (events.js:98:17)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (child_process.js:809:12)
gyp ERR! System Darwin 13.3.0
gyp ERR! command "node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/aglio/node_modules/protagonist
gyp ERR! node -v v0.10.29
gyp ERR! node-gyp -v v1.0.1
gyp ERR! not ok

> [email protected] install /usr/local/lib/node_modules/aglio/node_modules/chokidar/node_modules/fsevents
> node-gyp rebuild


gyp ERR! configure error
gyp ERR! stack Error: EACCES, mkdir '/usr/local/lib/node_modules/aglio'
gyp ERR! System Darwin 13.3.0
gyp ERR! command "node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/aglio/node_modules/chokidar/node_modules/fsevents
gyp ERR! node -v v0.10.29
gyp ERR! node-gyp -v v1.0.1
gyp ERR! not ok
npm ERR! [email protected] install: `node-gyp rebuild`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script.
npm ERR! This is most likely a problem with the protagonist package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     node-gyp rebuild
npm ERR! You can get their info via:
npm ERR!     npm owner ls protagonist
npm ERR! There is likely additional logging output above.
npm ERR! System Darwin 13.3.0
npm ERR! command "node" "/usr/local/bin/npm" "install" "-g" "aglio"
npm ERR! cwd /usr/local/lib/node_modules
npm ERR! node -v v0.10.29
npm ERR! npm -v 1.4.26
npm ERR! code ELIFECYCLE

> [email protected] install /usr/local/lib/node_modules/aglio/node_modules/socket.io/node_modules/engine.io/node_modules/ws
> (node-gyp rebuild 2> builderror.log) || (exit 0)


> [email protected] install /usr/local/lib/node_modules/aglio/node_modules/socket.io/node_modules/socket.io-client/node_modules/engine.io-client/node_modules/ws
> (node-gyp rebuild 2> builderror.log) || (exit 0)

npm WARN optional dep failed, continuing [email protected]
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     /usr/local/lib/node_modules/npm-debug.log
npm ERR! not ok code 0

Default content-type

Using the following code:

+ Response 200 (application/json)
    + Body

            {}

Doing aglio -i blueprint.md -o endpoints/index.html (with default template) will render correctly:

However, using a custom layout (this one : https://github.com/AnyFetch/developers.anyfetch.com/blob/gh-pages/_layouts/aglio.jade) and aglio -i blueprint.md -o endpoints/index.html -t _layouts/aglio.jade render this:

(note the undefined, instead of Content-Type).

I can't find anything wrong with my template, is it an error in aglio?

Aglio outputs nothing

Hi,

I'm running Ubuntu server 14.04.1 LTS. Installed node via "apt-get install node" and installed aglio via "npm install -g aglio".
Aglio is global available but when I run the command "aglio -i input.md -o test.html" test.html is not created. Also piping ("aglio -i input.md -o -") and "aglio -l" displays nothing.

How can I fix that?

Cache assets locally for offline developing

Do you manage to add this ?

Is using a custom theme with local assets a good alternative for you ?

Clarify rendering of action-specific parameters.

Currently, if I specify a URI parameter on my resource, I MUST include all the parameters, even if some are only relevant to a subset of the actions on that resource. (This is an understood issue with the specification.)

I'd prefer to have the documentation not repeat the irrelevant parameters when rendering the block for a particular action, as it's confusing to readers to see those extra params when they can't be used. See this discussion for a lot more comments on this debate.

Any chance aglio would change the output to help make this clearer, as Apiary is supposedly doing with their doc generator?

Support for different port?

It would be nice if there were a way to specify the port through the cli.

GET is being split from the section

Not really an issue (I think) but rather a question on why this happens. Consider this:

## Product [/product]
### Create [POST]
...

### Update [PUT]
...

### Get [GET]
...

### Delete [DELETE]
...

All sections are nicely rendered in the side menu, something like this:

Product
   Create
   Update
   Get
   Delete

There is however a problem, the GET usually requires an ID (GET /product/{product_id}) - which is a different URL. Now, my question is, how can I include the different GET URL in the document so it does still maintain the GET as part of the same menu indentation.

Any ideas?

Output html that can be opened directly in the browser (without a server)

It would be really nice for other developers if they could view the api without starting a server. Starting a server creates an extra step that is annoying and a little scary (for other people).

It does seem like the layout I'm using right now (default-multi) is working perfectly without a server. The only problem is that there's a huge banner saying This page may not display correctly when opened as a local file. Instead, view it from a web server., which can't be closed. If it could be closed, it would pretty much fix this issue. I would prefer a more general solution where aglio can output files that can be viewed without a server though.

Sidebar not rendering correctly

When there is only 1 request defined in a URI template, only the URI template's name is shown in the sidebar, and not the request.

Info: API Blueprint AST Media Types v2.0

For your information: Breaking dependency change.

As of Protagonist v0.10.0 the API, or more precisely the structure of the ast filed of the result object has been changed to conform to the new (JSON) AST Media Type v2.0. An update on you side might be needed when upgrading to the latest Protagonist.

Sorry about the troubles. Avoiding backward incompatible changes is my priority but this one was much needed to address some design flaws of the original version.

Discussion markup in Request payload section

Hi there,

According to the spec:
https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#5-payload-section-structure

It should be possible to add some markup to a request before its Headers (for ex). But aglio seems to ignore it, is this a known issue? any hints?

thanks!

Overlapping columns in the output html?

I am getting a funky issue with the way the page is rendered. The right and left columns are overlapping. See attached image. Any ideas what might be causing this and/or how to fix it? Thanks!

Use hash instead of timestamp for header links

This should help prevent some of the git commit churning when generating examples.

I18n?

Great piece of software and professionally looking templates. Thank you very much. But what about i18n? Do you have any plans for that? From a quick web search, one possible approach would be using i18next with JADE, as described in [http://rbeere.tumblr.com/post/41212250036/internationalization-with-express-jade-and] and the obviously easier (but IMHO dirtier) option would be to simply translate the templates into specific languages and adding location_codes (e.g. default-de.jade , default-es.jade , ...).

Either way, I might be up for some PRs if you make up your mind. :)

Thoughts about external documents for a more thorough software documentation

Hello,

In the last few days I've been looking into API Blueprint for describing our APIs and aglio for generating the documentation as HTML. I really like the current approach using the jade template engine and the simplicity of generating the templates from the abstract syntax tree.

I would however like to work on extending aglio to support external documents that can be included as part of the documentation. I'm thinking of more architectural documents and company related resources that are not directly related to the HTTP API usage.

I guess that these documents are kind of an extension to the "API Name & Overview Section" of the API Blueprint specification. But in order to keep things organized, it would be preferable to exclude these documents from the actual blueprint, in order to keep it focused.

I believe that this should be an aglio feature and unrelated to the actual blueprint.
The documents should be present in the navigation menu or be linked from other documents.

My goal with this post is to hear your thoughts about this, and get a discussion going. Then I'll be looking into whether or not it is something that I want to continue with, if people thinks that it has potential.

Best,
Tommy

Normalize link names for both types of templates.

If you change from a single to multiple page template, the name of the links for groups, resources, and actions also change. It would be nice if those link names were the same across the different types of templates.

It may also be nice to define a way in the markdown to better link to other resources in the document.

Bug: Template Stops Rendering New Updates

I was editing the _bootstrap-layout.jade to add styles for a form to send ajax/socket test calls to the server. It seems that no matter how many changes I do now, it remains the same. So there is a bug somewhere with a file refusing to update/rewrite.

output not shown in outputfile

Hi i am using aglio to convert md file to html in windows.

I use :
aglio -i inputfile.md -o outputfile.html

I see the output int the commandline and not in the html.

Can you help me on this.

Q: Include into existing page

I use Node and Jade in me application.
Is there any method to include the page directly to me page?
I want get this in one tab menu.
I saw, there is possible create own templates, this cool.
But is there any possibility to parse custom page with custom template?

Thank you

aglio hangs if request body starts with ------------------------------

If I call aglio with the following it does not return for at least 10 minutes.

FORMAT: 1A

# Test API

A test.

# POST

+ Request

    + Body

            ------------------------------107cd2e1026c

Calling snowcrash directly works.
It used to work with 1.16.1.
It also works if the number of -is reduced.

Support reading md from stdin

It would be really nice if the aglio command could take in markdown from stdin as opposed to just the -i flag. It's useful when incorporating aglio into a larger shell-based pipeline and creating intermediary files is inconvenient.

Output JSON Schema if present

Warning: I have never touched node in my life.

Would it be possible to also display the schema as well as the header and body.

I tried updating the _bootstrap-mixins.jade file with

if request.schema
    h5 Schema
    pre
        code!= highlight(request.schema)

But that seemed to have no effect.

I have tried converting the .md file using snowcrash directly and the schema section is output.

coffe-script error

When using node module. Get error

Cannot find module 'coffee-script']
code: 'MODULE_NOT_FOUND',

for /aglio/templates/_bootstrap-mixins.jade'.

Maybe just not use coffee and cut out unnecessary dependency? Whats wrong with JS?

Choices get cuts on long choice list

Here is an example:

ERR! [email protected] install: `node-gyp rebuild`

Hi there!

I'm trying to install it, but I'm having an issue:

$ sudo npm install -g aglio

npm http GET https://registry.npmjs.org/aglio
npm http 304 https://registry.npmjs.org/aglio
npm http GET https://registry.npmjs.org/coffee-script
npm http GET https://registry.npmjs.org/marked
npm http GET https://registry.npmjs.org/jade
npm http GET https://registry.npmjs.org/optimist
npm http GET https://registry.npmjs.org/protagonist
npm http GET https://registry.npmjs.org/highlight.js
npm http GET https://registry.npmjs.org/moment
npm http GET https://registry.npmjs.org/stylus
npm http GET https://registry.npmjs.org/cli-color
npm http 304 https://registry.npmjs.org/marked
npm http 304 https://registry.npmjs.org/coffee-script
npm http 304 https://registry.npmjs.org/optimist
npm http 304 https://registry.npmjs.org/jade
npm http 304 https://registry.npmjs.org/protagonist
npm http 304 https://registry.npmjs.org/highlight.js
npm http 304 https://registry.npmjs.org/moment
npm http 304 https://registry.npmjs.org/cli-color
npm http 304 https://registry.npmjs.org/stylus
npm http GET https://registry.npmjs.org/es5-ext
npm http GET https://registry.npmjs.org/memoizee
npm http GET https://registry.npmjs.org/wordwrap
npm http GET https://registry.npmjs.org/minimist
npm http GET https://registry.npmjs.org/mkdirp
npm http GET https://registry.npmjs.org/css-parse
npm http GET https://registry.npmjs.org/mkdirp
npm http GET https://registry.npmjs.org/debug
npm http GET https://registry.npmjs.org/sax
npm http GET https://registry.npmjs.org/glob
npm http GET https://registry.npmjs.org/commander/2.1.0
npm http GET https://registry.npmjs.org/transformers/2.1.0
npm http GET https://registry.npmjs.org/character-parser/1.2.0
npm http GET https://registry.npmjs.org/monocle/1.1.51
npm http GET https://registry.npmjs.org/with
npm http GET https://registry.npmjs.org/constantinople
npm http 304 https://registry.npmjs.org/memoizee
npm http 304 https://registry.npmjs.org/es5-ext
npm http 304 https://registry.npmjs.org/minimist
npm http 304 https://registry.npmjs.org/wordwrap
npm http GET https://registry.npmjs.org/event-emitter
npm http 304 https://registry.npmjs.org/mkdirp
npm http GET https://registry.npmjs.org/next-tick
npm http 304 https://registry.npmjs.org/css-parse
npm http 304 https://registry.npmjs.org/mkdirp
npm http 304 https://registry.npmjs.org/debug
npm http 304 https://registry.npmjs.org/sax
npm http 304 https://registry.npmjs.org/glob
npm http 304 https://registry.npmjs.org/commander/2.1.0
npm http 304 https://registry.npmjs.org/transformers/2.1.0
npm http 304 https://registry.npmjs.org/character-parser/1.2.0
npm http 304 https://registry.npmjs.org/monocle/1.1.51
npm http GET https://registry.npmjs.org/ms/0.6.2
npm http GET https://registry.npmjs.org/inherits
npm http GET https://registry.npmjs.org/minimatch
npm http 304 https://registry.npmjs.org/with
npm http 304 https://registry.npmjs.org/constantinople
npm http 304 https://registry.npmjs.org/event-emitter
npm http 304 https://registry.npmjs.org/next-tick
npm http GET https://registry.npmjs.org/readdirp

> [email protected] install /usr/local/lib/node_modules/aglio/node_modules/protagonist
> node-gyp rebuild

  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/HTTP.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/MarkdownBlock.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/MarkdownParser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/Parser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/ParserCore.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/Serialize.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/SerializeJSON.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/SerializeYAML.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/UriParser.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/snowcrash.o
  CXX(target) Release/obj.target/libsnowcrash/snowcrash/src/posix/RegexMatch.o
  LIBTOOL-STATIC Release/snowcrash.a
libtool: unrecognized option `-static'
libtool: Try `libtool --help' for more information.
make: *** [Release/snowcrash.a] Error 1
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:267:23)
gyp ERR! stack     at ChildProcess.EventEmitter.emit (events.js:98:17)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (child_process.js:797:12)
gyp ERR! System Darwin 13.3.0
gyp ERR! command "node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/aglio/node_modules/protagonist
gyp ERR! node -v v0.10.26
gyp ERR! node-gyp -v v0.12.2
gyp ERR! not ok 
npm http GET https://registry.npmjs.org/uglify-js
npm http GET https://registry.npmjs.org/uglify-js
npm http 304 https://registry.npmjs.org/inherits
npm http GET https://registry.npmjs.org/promise
npm http GET https://registry.npmjs.org/css
npm http GET https://registry.npmjs.org/uglify-js
npm http 304 https://registry.npmjs.org/minimatch
npm http GET https://registry.npmjs.org/lru-cache
npm http GET https://registry.npmjs.org/sigmund
npm http 304 https://registry.npmjs.org/uglify-js
npm http 304 https://registry.npmjs.org/promise
npm http GET https://registry.npmjs.org/async
npm http GET https://registry.npmjs.org/source-map/0.1.34
npm http GET https://registry.npmjs.org/uglify-to-browserify
npm http 304 https://registry.npmjs.org/css
npm http 304 https://registry.npmjs.org/uglify-js
npm http GET https://registry.npmjs.org/is-promise
npm http GET https://registry.npmjs.org/css-parse/1.0.4
npm http GET https://registry.npmjs.org/css-stringify/1.0.5
npm http 304 https://registry.npmjs.org/ms/0.6.2
npm http GET https://registry.npmjs.org/source-map
npm http 304 https://registry.npmjs.org/lru-cache
npm http 304 https://registry.npmjs.org/sigmund
npm http 304 https://registry.npmjs.org/async
npm http 304 https://registry.npmjs.org/readdirp
npm http 304 https://registry.npmjs.org/uglify-js
npm http 304 https://registry.npmjs.org/source-map/0.1.34
npm http 304 https://registry.npmjs.org/uglify-to-browserify
npm http 304 https://registry.npmjs.org/is-promise
npm http 304 https://registry.npmjs.org/css-parse/1.0.4
npm http 304 https://registry.npmjs.org/source-map
npm http 304 https://registry.npmjs.org/css-stringify/1.0.5
npm http GET https://registry.npmjs.org/amdefine
npm http 304 https://registry.npmjs.org/amdefine
npm ERR! [email protected] install: `node-gyp rebuild`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] install script.
npm ERR! This is most likely a problem with the protagonist package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     node-gyp rebuild
npm ERR! You can get their info via:
npm ERR!     npm owner ls protagonist
npm ERR! There is likely additional logging output above.

npm ERR! System Darwin 13.3.0
npm ERR! command "node" "/usr/local/bin/npm" "install" "-g" "aglio"
npm ERR! cwd /Users/xxx/sites/xxx/xxx
npm ERR! node -v v0.10.26
npm ERR! npm -v 1.4.3
npm ERR! code ELIFECYCLE
npm ERR! 
npm ERR! Additional logging details can be found in:
npm ERR!     /Users/xxxx/sites/xxx/xxxx/npm-debug.log
npm ERR! not ok code 0

Any clue?

SegFault

Using following blueprint (which I assumed to be valid, pass on apiary) :

# Index page [/]
Retrieve datas about the current account

## Retrieve Entry Point [GET]
Something.

I get a SEGAULT [1] 15180 segmentation fault (core dumped) aglio -i blueprint.md -o doc.html

When using node code, i get the (more?) detailed information:

parser exception: 'basic_string::substr'

Themes: Print CSS for at least one

It would be brilliant to have at least one theme with a print css.

table of contents (instead of navigation)
no more toggle-links and always display sample request/response

That would be such a great help to created PDF documentations out of the md and use it it normal business environments (…where there is always a need to send PDF API Docs to third-party developers).

Rendering Response description

Based on this it should be possible to add a description to a Response without having to add a mime type and still have the comment appear. But this doesn't work in aglio. If I put the mime type I see the comment (and header), if I don't put a mime type I get nothing. Thanx!

Unable to install aglio

Hi I am unable to install aglio. I get following error.

[email protected] install C:\Users\gs1460\AppData\Roaming\npm\node_modules\aglio\node_modules\protagonist
node-gyp rebuild

:\Users\gs1460\AppData\Roaming\npm\node_modules\aglio\node_modules\protagonist>node "C:\Program Files\nodejs\node_modules\npm\bin\node-gyp-bin....\node_modules\node-
uilding the projects in this solution one at a time. To enable parallel build, please add the "/m" switch.
SBUILD : error MSB3428: Could not load the Visual C++ component "VCBuild.exe". To fix this, 1) install the .NET Framework 2.0 SDK, 2) install Microsoft Visual Studio 20
e component to the system path if it is installed elsewhere. [C:\Users\gs1460\AppData\Roaming\npm\node_modules\aglio\node_modules\protagonist\build\binding.sln]
SBUILD : error MSB3428: Could not load the Visual C++ component "VCBuild.exe". To fix this, 1) install the .NET Framework 2.0 SDK, 2) install Microsoft Visual Studio 20
e component to the system path if it is installed elsewhere. [C:\Users\gs1460\AppData\Roaming\npm\node_modules\aglio\node_modules\protagonist\build\binding.sln]
yp ERR! build error
yp ERR! stack Error: C:\Windows\Microsoft.NET\Framework\v4.0.30319\msbuild.exe failed with exit code: 1
yp ERR! stack at ChildProcess.onExit (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\build.js:267:23)
yp ERR! stack at ChildProcess.emit (events.js:98:17)
yp ERR! stack at Process.ChildProcess._handle.onexit (child_process.js:809:12)
yp ERR! System Windows_NT 6.1.7601
yp ERR! command "node" "C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" "rebuild"
yp ERR! cwd C:\Users\gs1460\AppData\Roaming\npm\node_modules\aglio\node_modules\protagonist
yp ERR! node -v v0.10.29
yp ERR! node-gyp -v v0.13.1
yp ERR! not ok
pm ERR! [email protected] install: node-gyp rebuild
pm ERR! Exit status 1
pm ERR!
pm ERR! Failed at the [email protected] install script.
pm ERR! This is most likely a problem with the protagonist package,
pm ERR! not with npm itself.
pm ERR! Tell the author that this fails on your system:
pm ERR! node-gyp rebuild
pm ERR! You can get their info via:
pm ERR! npm owner ls protagonist
pm ERR! There is likely additional logging output above.

pm ERR! System Windows_NT 6.1.7601
pm ERR! command "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "install" "-g" "aglio"
pm ERR! cwd C:\Users\gs1460
pm ERR! node -v v0.10.29
pm ERR! npm -v 1.4.14
pm ERR! code ELIFECYCLE

Can you help in moving forward.

Working on windows

Hi. Maybe i'm doing something wrong, but aglio doesn`t work for me on Windows. Steps:

Install via npm and run

npm install -g aglio

aglio  -i example.md -s

example.md - example file from https://raw.github.com/danielgtaylor/aglio/master/example.md
3. Go to http://localhost:3000
4. Server crashes and what i get in output:

Server started on http://localhost:3000/
Rendering example.md

http.js:783
    throw new TypeError('first argument must be a string or Buffer');

TypeError: first argument must be a string or Buffer
    at ServerResponse.OutgoingMessage.write (http.js:783:11)
    at ServerResponse.OutgoingMessage.end (http.js:964:16)
    at C:\Users\Admin\AppData\Roaming\npm\node_modules\aglio\lib\bin.js:89:22
    at C:\Users\Admin\AppData\Roaming\npm\node_modules\aglio\lib\main.js:68:16
    at Object.exports.render (C:\Users\Admin\AppData\Roaming\npm\node_modules\aglio\lib\main.js:64:24)
    at Server.<anonymous> (C:\Users\Admin\AppData\Roaming\npm\node_modules\aglio\lib\bin.js:84:22)
    at Server.EventEmitter.emit (events.js:98:17)
    at HTTPParser.parser.onIncoming (http.js:2056:12)
    at HTTPParser.parserOnHeadersComplete [as onHeadersComplete] (http.js:120:23)
    at Socket.socket.ondata (http.js:1946:22)

After removing all content i found that line that causes crash is

# Group Notes

So if i run aglio on empty file - everything works fine. But if i add line with Group - server crashes.
Also i have this error:

C:\Test>aglio  -i example.md -o -
>> {"code":1,"message":"parser exception has occured","location":[],"input":"# Group Notes"}

Maybe something with my enviroment? Windows Server 2008 R2, node 0.10.13

Can't load aglio as a library in windows

When I try and load it in as a library, the require command fails with the following message:

module.js:340                                             
    throw err;                                            
          ^                                               
Error: Cannot find module 'aglio'                         
    at Function.Module._resolveFilename (module.js:338:15)
    at Function.Module._load (module.js:280:25)           
    at Module.require (module.js:364:17)                  
    at require (module.js:380:17)                         
    at Object.<anonymous> (C:\dev\aglio_test\index.js:1:75)  
    at Module._compile (module.js:456:26)                 
    at Object.Module._extensions..js (module.js:474:10)   
    at Module.load (module.js:356:32)                     
    at Function.Module._load (module.js:312:12)           
    at Function.Module.runMain (module.js:497:10)

However, if I cd into the aglio folder in node_modules and run npm install && grunt compile, the module seems to be loading properly.

Is this a coffeescript issue or something to do with windows?

Error : resource model can be specified only for a named resource, name your resource...

I have this error when I launch "aglio -i input.md -o output.html" (my input.md is your example.md)
I just installed aglio via npm today
Can you help me ?

Line 34: resource model can be specified only for a named resource, name your resource, e.g. '# <resource name> []' (error code 3)

Models can only be referenced if defined above

It seems that resource links for model responses are only usable if they have been defined previously, which can lead to circular dependencies in complex layouts.

Line 296: undefined symbol 'Places' (error code 3)

It exists, just... later in the file. :)

Protagonist causes 'Segmentation fault: 11'

When running aglio as a node library, it fails when parsing the blueprint using protagonist. Strangely, as a global executable parsing the same output, it works fine.

Segmentation fault: 11
node(15630,0x103a0f000) malloc: *** error for object 0x100c0a388: pointer being freed was not allocated
*** set a breakpoint in malloc_error_break to debug
Abort trap: 6

Any ideas?

URL gets cut off at the right edge of the page

If the URL is too long, then it gets cut off at the right edge of the page. I don't have a preference for how it gets fixed so long as its visible in some form.

Example below: