Hyperapp: Move docs to repo.

[jorgebucaran]

I moved the docs to the wiki because that way they're easier to update (quickly and a lot) as well as accept user contributions (it's public so anyone can fix anything). Now that GitHub's wiki code highlighting is suddenly broken, I've had a chance to think about this again and would like to consider moving the docs to the repo instead. Still thinking about it.

+

• Docs are always in sync with code after a release.
• No more weird wiki issues.

-

• More difficult to contribute. People need to fork and send a PR.
• More difficult to navigate; the wiki has a nice right side navigation panel.

[FlorianWendelborn]

➕Documentation is included in local copies of hyperapp. No separate repo to clone (wikis are repos too).
➕Documentation can therefore be easier viewed in user's editors and in CLI interfaces.

[jorgebucaran]

Another con is that wiki's don't support <details>, though that could change.

Wiki's have other quirks (or features) too, like [[Links]] style links, footers and headers. They're really nice.

@dodekeract If I move the docs to the repo, what do you suggest we do with the wiki feature?

I suggest we close it.

[FlorianWendelborn]

I personally don't like the wiki, but that's mostly because it's a separate repo. If GitHub would just allow to store it in /.github/wiki or allow setting an arbitrary folder it'd be a nice feature.

[jorgebucaran]

@dodekeract If it'd work like an in-repo gitbook, that'd be amazing.

[lukejacksonn]

you could kind of achieve that using the /docs folder as the github-pages root.. but it would require a little frontend app index.html to route, fetch and render markdown 🔍 🤔

[jorgebucaran]

@lukejacksonn Haha 😉

[grantcarthew]

Hey @jbucaran I just found your hyperapp thanks to EchoJS. Looks great although I am in the middle of learning Vuejs.

Some feedback on this issue.
@dodekeract is not quite correct. See my automation site repo: https://github.com/grantcarthew/site-auto-tech

I am using the GitHub Wiki for my job queue: https://github.com/grantcarthew/node-rethinkdb-job-queue

After using it for a while now there is only one downside I can see. The documentation is not versioned with the project. I have only recently started rectifying this by adding version info into the documents. Here is an example: https://github.com/grantcarthew/node-rethinkdb-job-queue/wiki/Queue.process#partly-completed-or-delayed-job

On the positive side of things:

• You can't beat the [[ ]] linking to other documents! This is the best documentation feature.
• The sidebar makes for a great navigation tool.
• I only use the browser to edit pages. I have read elsewhere how people think this is crazy but it is so easy and quick.
• If I make sweeping changes to the project, I update my clone of the wiki and find/replace with ease.
• Because it is so easy to write the documents my documentation is extreme.

Some of the negative points above could be fixed by cloning the docs and adding them to a docs directory prior to publishing new version. This would allow people to read from their editor however the navigation and [[ ]] linking would not function.

Just trying to help with your decision.

[grantcarthew]

Oh, and this is probably why your markdown rendering has changed:

https://github.com/blog/2333-a-formal-spec-for-github-flavored-markdown

[jorgebucaran]

@grantcarthew Thanks for chiming in 👋.

I agree with all your points above, strongly. That's why we're using a wiki. The recent incident is also directly related to the link you posted and also confirmed by @vmg here.

Nevertheless, @dodekeract's argument that using a single repo for everything is more consistent, is also true. This may seem like a trivial decision, but it's one that will affect my future projects too so I'm still trying to decide what's the best action to take.

For example, if we move the docs to the repo, what will we use the wiki for?

[grantcarthew]

@jbucaran This is how I see it. The docs are disconnected from the project. This means your git history for the project is code only. It also means if I see a letter out of place whilst reading/reviewing the docs, hit edit, fix letter, save. None of that mess will be in the projects git history, branch or not.

With that said. Having the docs with the project will make them locked to the versions which is a enormous plus.

The benefits of the wiki out way the negatives in my case. They may not in yours.

Food for thought. Out of all the online documentation I consume for JS, the best example that comes to mind is Express.js. The reason I love it so much is simply for the Ctrl-F functionality. Everything is on the one page.

[lukejacksonn]

So tonight I made a (precariously dodgey 😅) hyperapp that serves up its own docs from github-pages. It was based off of a clone of hyperapp.wiki and I tried to change as little as possible. Not tried solving the [[Link]] syntax yet but I believe it would be trivial to implement now.

Repo: https://github.com/lukejacksonn/hyperapp-wiki
Demo: https://lukejacksonn.github.io/hyperapp-wiki

With this setup, the docs could live and be served from the /docs directory of the hyperapp repository. I'm not saying we should do this but knew it was possible so thought it would be fun to whip up a POC.

The functionality is still very basic.. and it feels jarring because I have not implemented intercepting route changes yet (this https://github.com/hyperapp/hyperapp/pull/150 would help.. nudge, nudge, wink, wink) so all fetching of markdown is handled by the subscriptions.

It does however support code blocks with syntax highlighting.. and emojis 🎉

[FlorianWendelborn]

You can't beat the [[ ]] linking to other documents! This is the best documentation feature. — @grantcarthew

You can use [source](/documentation/example.md) to do the same thing. Doesn't even break markdown.

I only use the browser to edit pages. I have read elsewhere how people think this is crazy but it is so easy and quick. — @grantcarthew

I usually clone wikis and symlink them into my project folder.

[grantcarthew]

Ok, great info @dodekeract thanks.

[jorgebucaran]

@dodekeract I usually clone wikis and symlink them into my project folder.

Do you really _usually_ do this? 🙄

[FlorianWendelborn]

@jbucaran For work-related wikis, yes. I don't like editing files in my browser. Doesn't have 1% of the features I'm used to in atom. So whenever I'm using a wiki more than once I clone it into ~/code/namespace/... and symlink that folder into ~/.atom/projects/....

My atom is for example set-up to auto-format markdown tables to be perfectly aligned and I'm used to editing files on multiple lines at the same time. Also the real-time split-screen markdown-preview is quite useful.

That being said - I also usually don't use wikis. I don't like them so none of my repos use them.

[jorgebucaran]

BTW https://github.com/hyperapp/hyperapp/tree/docs

[vmg]

Hello folks! Just a heads up that syntax highlighting has been fixed in wikis. Some old pages may still be cached, so just editing them will cause the syntax highlighting to show up again.

Sorry for the inconvenience!

[jorgebucaran]

@vmg Thanks for the heads up.

[jorgebucaran]

I've spent a lot of time thinking about the issue and not making a decision is just slowing things down around here, so I'll stick with the original plan and continue to use the wiki. I feel this is quirky

@lukejacksonn That POC hyperapp looks pretty cool man. Do you have any exciting plans? I hope you don't drop the project now that I'm gonna keep the wiki around.

[FlorianWendelborn]

@jbucaran It's probably possible to adapt this to serve the wiki, lol.

[jorgebucaran]

I thought it was already serving the wiki.

[FlorianWendelborn]

@jbucaran Then I don't know why @lukejacksonn should drop the project.

[lukejacksonn]

So my demo looks in /pages/${path}.md the root is relative to the server.. so if you are on localhost it _fetches_ from https://localhost:8080/pages/${path}.md but when it detects it is being ran from *.github.io then it will fetch markdown from https://organization.github.io/repo/pages/${path}.md.

There is no reason why we can't say to it.. go look at ${wiki-repo}/pages/${path}.md