{"action":"opened","issue":{"url":"https://api.github.com/repos/sphereio/sphere-api-reference/issues/7","labels_url":"https://api.github.com/repos/sphereio/sphere-api-reference/issues/7/labels{/name}","comments_url":"https://api.github.com/repos/sphereio/sphere-api-reference/issues/7/comments","events_url":"https://api.github.com/repos/sphereio/sphere-api-reference/issues/7/events","html_url":"https://github.com/sphereio/sphere-api-reference/issues/7","id":93523355,"number":7,"title":"Agree on markdown validation rules & if markdown lives inline or in include","user":{"login":"nkuehn","id":4006139,"avatar_url":"https://avatars.githubusercontent.com/u/4006139?v=3","gravatar_id":"","url":"https://api.github.com/users/nkuehn","html_url":"https://github.com/nkuehn","followers_url":"https://api.github.com/users/nkuehn/followers","following_url":"https://api.github.com/users/nkuehn/following{/other_user}","gists_url":"https://api.github.com/users/nkuehn/gists{/gist_id}","starred_url":"https://api.github.com/users/nkuehn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nkuehn/subscriptions","organizations_url":"https://api.github.com/users/nkuehn/orgs","repos_url":"https://api.github.com/users/nkuehn/repos","events_url":"https://api.github.com/users/nkuehn/events{/privacy}","received_events_url":"https://api.github.com/users/nkuehn/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-07-07T12:49:22Z","updated_at":"2015-07-07T12:49:22Z","closed_at":null,"body":"The local validator has a markdown-linter.  It is not \"hot\", so the tests don't fail because we have to agree on the set of rules first. \r\n\r\nCurrent setting here lets the linter complain a lot about list indentation:  https://github.com/sphereio/sphere-api-reference/blob/master/bin/explode-raml.js#L26  \r\n\r\nTo be able to set the rules sensibly we need to decide whether the MD texts will live in separate *.md  files in the future or will remain inlined in the RAML. \r\n\r\nI personally prefer separate files with a strict naming convention because that would make it easier for others (e.g. SDKs) to auto-include the content in their documenation generators. Also, you get tool support when writing the stuff.  CON: content very spread out. \r\n\r\n\r\n"}}