I'm passionate about 🎬 live video streaming, 🛠 HTTP & REST APIs and developer tooling like 📦 SDKs & 🖥 CLIs
danielgtaylor / aglio Goto Github PK
View Code? Open in Web Editor NEWAn API Blueprint renderer with theme support that outputs static HTML
An API Blueprint renderer with theme support that outputs static HTML
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.
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
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?
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)
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.
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: [] }
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
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?
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!
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?
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
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?
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?
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.
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.
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
Hi. Maybe i'm doing something wrong, but aglio doesn`t work for me on Windows. Steps:
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
It would be nice if there were a way to specify the port through the cli.
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.
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?
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
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?
~$ 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?
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?
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.
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.
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
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> GET /resources/
</a>
<a href="#foobar-" class="list-group-item">
<i class="fa fa-arrow-circle-down"></i> GET /resources/?limit={page_limit}
</a>
<a href="#foobar-" class="list-group-item">
<i class="fa fa-arrow-circle-down"></i> GET /resource/{id}/
</a>
</div>
<!-- MAIN -->
<h4 id="foobar-">
Foobar
<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.
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?
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.
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.
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.
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. :)
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
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.
Do you manage to add this ?
Is using a custom theme with local assets a good alternative for you ?
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. :)
Scenario:
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.
This should help prevent some of the git commit churning when generating examples.
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!
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'
It would be brilliant to have at least one theme with a print css.
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).
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.
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.
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?
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.