Read the Docs meets Gist.io for simple Markdown project documentation
Home Page: http://viewdocs.io
Viewdocs is Read the Docs meets Gist.io for simple Markdown project documentation.
See it in action at http://viewdocs.io/
Hey @progrium,
First of all, thanks for this awesome project! I really like the idea and I think it makes up for a pretty awesome alternative to github pages for documentation! The fact that you don't need to manage a separate branch neither you need to resort to things like Jekyll or Middleman to have something more "advanced" (like layouts) has hit me pretty hard :)
So I was wondering how it could be improved and I came up with a few things that I'd like to know your thoughts before attempting my first ever Golang pull request :P
This is related to the rest of the stuff described below and it is about having some sort of metadata bundled with the project. Maybe some viewdocs.json on the project root that gives viewdocs some insights about the project when building it.
Well... you know.... things changes and a new feature might have been introduced on a version that also has a breaking change that prevents people from upgrading. If we keep displaying only the docs from the master branch it might end up getting some people into trouble.
My idea was to leverage GitHub's release api and build docs for specific versions. Something like http://<github-username>.viewdocs.io/<repository-name>/<version> and use latest as the version for the current master or we could require users to list all versions on the JSON manifest file in order to make things less "magical".
GitHub has the automatic page generator and for smaller projects I think a README is enough. So my idea was to have a fallback to rendering the README in case the docs folder is not found. There's still the issue of specifying a pre made layout and a Google Analytics tracking code but this information could also be kept on the JSON manifest :)
I'm not really sure if it would be possible to somehow automatically grab the pre made github templates but I'm fine with marking that "out of scope" :P
I'm not 100% sold on this one yet but apart from the README fallback we might also have support for rendering changelogs in a nice looking page. I'm also fine with not having this feature, just wanted to know your thougts on it as it is something that has crossed my mind.
I hope you like the ideas or that at least it gives you some food for thought :)
I made a change to my template.html file this morning (a change from a textual link to my github repo to the 'fork me on github' ribbon').
I was proudly showing off my viewdocs site to a student when I noticed that he retrieved a page showing the textual link, not the github ribbon.
This student had never retrieved the site before, so it wasn't because he had a local cache of the page.
After he manually refreshed the page, it displayed the ribbon.
I am guessing from this behavior that viewdocs somehow caches the rendered pages and does not invalidate the cache when a new template.html file is committed?
Which brings up another question I have been meaning to ask: how the heck does viewdocs actually work? Where are my rendered files being stored, for example? Who do I thank for paying for the storage/computational requirements for this service?
Using the default template supplied in the repo, it seems that the following markdown options don't make their way into the final html page:
When linking between documents, the links are not automatically adapted to fit viewdocs link structure.
If i follow the structure of the links in your examples to create relative links between my pages, then the github markdown viewer's linking is broken.
For example, linking to my "object-collection.md" page using the github navigation works perfectly, but doesn't on viewdocs because it doesn't adapt the link automatically to "http://crazycodr.viewdocs.io/data-collection/object-collection.md" and instead assumes that my link is "http://crazycodr.viewdocs.io/object-collection" which is totally wrong.
To fix this with viewdocs, i'd have to hardcode all my relative links with "data-collection/object-collection.md" but after doing that, obviously, people can't navigate using the integrated github markdown viewer...
What is you take on this? Anything planned or actually exists to fix this?
I'm planning to use viewdocs for some of my projects and it would be really nice to have a way to run the server locally to preview the changes I'm making without the need to push to github and wait for the cache to expire.
What would be the best way to handle that? I'm up for doing the required changes if we agree on how that should work :)
Would be super nice to include image loading via GitHub.
For example:
http://couchapp.viewdocs.io/couchapp/gettingstarted.md
vs.
https://github.com/couchapp/couchapp/blob/master/docs/gettingstarted.md
Thanks!
given
<navbar heading="Angular Pouch Model" name={{NAME}} user={{USER}} ></navbar>
The user attribute value is set to: marfarma -- as expected. But with the self-closing tag, as below,
<navbar heading="Angular Pouch Model" name={{NAME}} user={{USER}}/>
the user attribute value is set to: marfarma/ -- it picks up a trailing slash.
How could I theoretically misuse viewdocs to link to a private, but public gogs instance offering simple git editing for low end users?
In combination with viewdocs, we have a decoupled CMS.
What should I do?
html (not in a code block) is valid markdown. However, when I did this:
<div id="jsonnav">
{"content":"some json content"}
</div>
or this:
<div class="jsonnav">
{"content":"some json content"}
</div>
I got this:
<div>
{"content":"some json content"}
</div>
in my rendered page. The difficulty here is that when attempting to act on that div, I had to resort to an xpath selector to find it -- and that path changed every time I adjusted the layout in my template.
Eventually I may want to add other html that requires different attributes in order to render correctly (i.e. if I want to embed something, like a plunker example) and the work-around could be more painful, if those were stripped as well.
I thought I'd document a known issue even though I don't think there's much you can do about this unless you want to switch to a markdown engine w/ GFM support rather than GitHub's Markdown API (also suggested in #22).
GitHub previously only supported task lists in issues and commit comments, but now they work in all documents - including README.md. It'd be great to see the same behavior in viewdocs.
Grip explains:
GitHub introduced read-only task lists to all Markdown documents in
repositories and wikis back in April, but
the API doesn't respect this yet.
Just submitted a PR for people to check out my branch and it didn't work properly :( http://fgrehm.viewdocs.io/vagrant-cachier~docs (the links on the menu do not work)
I'll try to have a look at it later on to see if I can fix it
https://viewdocs.io/ does not work.
Looks like the app is running on Heroku so adding a free certificate using https://letsencrypt.org/ should not be difficult https://devcenter.heroku.com/articles/automated-certificate-management
This can be especially useful to those who do README driven development.
cujojs/when is an example of a project that uses README.md as an index for documentation, while putting other docs inside docs directory.
To implement this, some care must be taken in resolving relative links: links to images should be relative to the project's root, whereas links to pages inside the docs directory should have the docs component stripped out, and maybe, links to files outside the docs directory just link to the blob page on GitHub.
Currently, all links are prefixed with http://<github-username>.viewdocs.io/<repository-name>, but that prevents sub-directories from working (as they do on GitHub).
Example:
"What the HTTP is CouchApp?" on
http://couchapp.viewdocs.io/couchapp/couchapp-org/index.md
should link to
http://couchapp.viewdocs.io/couchapp/couchapp-org/what-is-couchapp.md
but actually links to
http://couchapp.viewdocs.io/couchapp/what-is-couchapp.md
which 404's.
The same content / paths work fine on GitHub's doc viewer:
https://github.com/couchapp/couchapp/blob/master/docs/couchapp-org/index.md
We previously discussed the lack of SSL, and how it's not possible to do it in heroku.
Something that could work is to change the URL structure to something like what's used by other projects:
This would remove the requirement for wildcard domains and certificates, making SSL easier to setup.
If breaking existing links under //viewdocs.io is a problem, you could use a fixed subdomain to work around it: https://secure.viewdocs.io/progrium/viewdocs. Unsure what a good subdomain would be, though.
Server down? Just got this:
<!--?xml version="1.0" encoding="utf-8"?--><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html><head>
<title>503 Connection timed out</title>
</head>
<body>
<h1>Error 503 Connection timed out</h1>
<p>Connection timed out</p>
<h3>Guru Meditation:</h3>
<p>XID: 3332983658</p>
<hr/>
<p>Varnish cache server</p>
</body></html>
Hey Jeff,
quick questions:
.github.com by .mygitserver.com ?Thanks
it'd be nice if viewdocs.io allowed folks to use links which work in any file system / github using the real source file name of the file (e.g. "foo.md" and then silently removed the ".md") (or generated a html alternative for it or something) so that links don't have to be 'special viewdocs.io format" with no file extension.
e.g. using the github way of navigating markdown files can be useful for folks who are editing the docs. Its a shame right now you need to use github links or viewdocs.io links but you can't have both.
It would be nice to be able to test styling changes on a specific branch before pushing it to master.
I've been wondering if it would make sense to have some sort of variable with the current page path for us to use on our template's <body> to have a better control of the styles / JS applied to each page.
I was thinking about some sort of {{PAGE_CLASSES}} variable that gets the current markdown document path value hitting some page. We'd just need to take into consideration paths with slashes and I think we can either make it 2 separate classes or just replace the /s with -s.
Just to make it easier to understand, http://progrium.viewdocs.io/viewdocs/development would set {{PAGE_CLASSES}} to development, while http://progrium.viewdocs.io/viewdocs/development/some-section could set {{PAGE_CLASSES}} to either development-some-section or development some-section
@progrium, I hope that's clear enough and please LMK if you'd accept a PR for that :-)
It's still a 'work in progress' but I'm happy enough with it that I thought I'd announce.
I've built a viewdocs.io compatible Bootstrap3, Angularjs template. Due to github's anti-hot linking policy, I had to inline css, javascript and templates, so the code's ugly as sin. It would be really nice if viewdocs.io would server other file types, css, js, json are the three that come to mind.
Navbar menu items are controlled by the contents of a markdown file that contains an array of names and href values in json format. The file has a .md extension because, due to 'same origin' security issues, the async call over to github.com failed. Since viewdocs.io won't server json files, I named it nav.md, and parse the returned html file to extract the json.
A sidebar menu linking to page sections - with an menu item for each h1 tag in the primary content -- is generated. Example: http://marfarma.viewdocs.io/angular-pouch-model/api
The template was coded to support other projects, but there's probably some bits I overlooked. If you try it out, let me know what you have to change to make it work for your project.
The tempate: https://github.com/MarFarMa/angular-pouch-model/blob/master/docs/template.html
The nav.md: https://github.com/MarFarMa/angular-pouch-model/blob/master/docs/nav.md
Written with StackEdit.
Template rendering doesn't replace {{user}} and {{name}} in script and stylesheet tags within the src attribute, although it does replace them in link href's. They are replaced in innerText, if it exists.
Seems other than 404 status codes leave unclosed resp.Body()
See:
https://github.com/progrium/viewdocs/blob/master/viewdocs.go#L115
https://github.com/progrium/viewdocs/blob/master/viewdocs.go#L215
Currently attempting to link to http://{{user}}.viewdocs.io/{{name}}/assets/app.js returns 404 - file not found. Github's anti-hot-linking provision prevents the use of http://raw.github.com/{{user}}/{{name}}/docs/assets/app.js As a workaround I've added my script code to my template using a script tag. The same issue exists for css and json files. While that's not too bad, what's really awful is that I've had to do the same with my customized bootstrap.css - add it to the head in a style tag.
And while json files don't suffer from Github's anti-hot-linking provision - they are subject to same-origin restrictions via ajax access - leading me to embed json in a markdown file, and then parse it out from the rendered template after it's fetched from the server. This is further made difficult by the attribute stripping from markdown included html - see my other issue.
Are image files served? I haven't tested that yet. If not, and they can't be hot-linked, they should also be supported.
If security is a concern, perhaps enforce that non-markdown files served must be included in a manifest file at the same location as the template (whether or not the template includes a manifest tag), or only server files local to the docs directory and it's children?
Reproduce
The screen.css suggests static.gist.io is a ZEiT now app
React
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
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
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.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.