Wiki proposal

[jacmoe]

I am working on Pype - which is Personal Yii Page Engine.

What it does is render markdown documents from a separate Git repository, and updates are automatically applied by a webhook.

It already supports a list of contributors for each page, and - with correct url routing - it also handles internal links to pages.

Meta information for each page is a piece of YAML in the page itself, like:

<!--
Title: Section
Description: This is the section
Keywords: wiki, yii, module, markdown, another
View: post
-->

That information, and more, is then parsed/computed and cached in a Flywheel repository (JSON data store) - each time a page changes or is created, the data is generated/rebuilt.

This is my idea of how a future wiki for Yii can be like.

I am building it to replace my current blog software, but it could potentially be useful, like for the Yii Wiki.

Looking forward to your questions / opinions / comments :)

[jacmoe]

[samdark]

Sounds cool but we have existing documents which are in the database. Also, I'm not sure how convenient it would be to use git instead of editing directly into UI...

[samdark]

Documents, of course, could be converted but I'm still worrying about missing UI.

[jacmoe]

Github has all the UI that you need.

Just edit, issue a PR, and then - if accepted - a webhook automatically updates the wiki by running a series of scripts.

Using Github gives authentication, versioning, access control (PR,etc) and contributors list.
It is neat.

Documents does not need to be converted that much. They are plain markdown, with some YAML frontmatter at the top - title, description, tags, etc.

[cebe]

There is a problem with edit links on github. If you click on an edit link for a repo that you do not have a fork of it will automatically fork it before you have edited anything.

Nevertheless an interesting idea.

[jacmoe]

I think I saw a different kind of link a short while ago that did not fork - I will see if I can find it :)

[jacmoe]

we have existing documents which are in the database

Yes, that is a pain in the backside.
With real documents it is easy to publish it as PDF, etc.

[jacmoe]

D'oh - it is actually quite simple: do not include edit in the edit link :+1:

Edit: just replace editwith bloband all is well.

No forks are created (or harmed) except when the user click the edit link on the page. (On Github). Like on Read the Docs: https://docs.nodebb.org/en/latest/installing/os.html

I will change that for Pype :)

[rob006]

How this will work with 1000 wiki articles in repository? We will have hundreds of files in single directory in repository?

[jacmoe]

Since it is using Flywheel for the db and filecache for caching, it could use Redis and Mongo if it was a problem.

[jacmoe]

If you really want a GUI interface - other than the excellent and battle-proven Github interface - there is nothing that prevents anyone from putting a front between the mdpages module and the wiki page..
The only that that is different from a normal approach is that instead of saving to a database, it is pushing to a repository.

[samdark]

GitHub is OK as long as there are links to it and old data is properly imported.

[jacmoe]

What I like about this - and I am of course highly biased - is that each document has it's meta data built into it (the frontmatter at the top) and that each document (page on the wiki) has a list of contributors.

The frontmatter would mean that each page in the wiki can have a proper description meta tag which could help search engines.
Also, the fact that the pages are text could also make it easier to hook it up with Elasticsearch, etc.
...

For me, that would be a nice improvement over the old wiki: that each page is a collaborative work and not owned by a particular person. That could help to ensure that the quality is kept high.

And the link to the source at each page would make it a fluent business for people who want to contribute. All they need is a Github account, and then Yii gets to take advantage of what Github has to offer: audit and user management.
It is also nice that the wiki is in a separate repository because then people could be made collaborators more easily.

Anyway, I am writing this to replace my current blogging platform, and also to be used in my other open source projects (my own read the docs software), so I am not going to be specifically dedicating it to the Yii project.
It could be a nice side-effect, though. ;)

[rob006]

@jacmoe I'm talking about structure of git repository with wiki content. As far as I understand it, right now page structure is the same as file structure in repository. So if we want 1000 wiki articles with urls like http://www.yiiframework.com/wiki/first-wiki-article-slug, http://www.yiiframework.com/wiki/second-wiki-article-slug, ... , we need repository with 1000 files/directories in repository root. Working with such a repository will be quite inconvenient.

[jacmoe]

I am not sure what you mean?

An article is a file.
So first-wiki-article-slug will be stored as first-wiki-article-slug.md in the repository.

However, if you put a file called slug.md in a directory, say: advanced/theming/twig it will get the following URL: http://www.yiiframework.com/wiki/advanced/theming/twig/slug.

In other words: the slug is just the directory structure. Quite intuitive if you ask me.

Internally, the file path is used as the parameter for the page/view action and then rewritten..

http://www.yiiframework.com/wiki/page/view?id=advanced%2Ftheming%2Ftwig%2Fslug

[rob006]

Right now Yii wiki is flat and have 767 articles. It means 767 files/directories in single directory in repository. Don't you think that working with such a long list of files in a single directory will be inconvenient?

[jacmoe]

Nope. Actually not.

If you really wanted to, all the wiki articles could go into the root directory.
The console command update is responsible for making sense of that wad of pages.
The information the script gathers is cached and that means that the only time the wiki engine has to process the raw repository is when a file changes (something is pushed to it), and then only the data related to the changed file is rebuilt.

Each wiki article has frontmatter:

<!--
Title: A long title that would be a bad fit for a filename
Description: What the article is about so that it can be used in the listings and on top of the page itself.
Tags: yii2, admin, rbac
-->

Then it is just a matter of running a simple query on the page collection. Like 'get all the pages tagged with "yii2" and sort them by date descending.

Or, if - and I think it would be a good idea - we started to use directories, then it could start with two directories: yii2 and yii1 and the URL becomes: http://www.yiiframework.com/wiki/yii2/wikiarticle

The directory is only read by a computer - or do I miss a point of yours?

[jacmoe]

Link to PhileCMS's docs because it could clarify some points: http://philecms.github.io/Phile/docs.html

I am writing Pype to replace it so it is quite similar.

[jacmoe]

You do have a point, of course, @rob006 - and I think that a project the size of Yii could use a well thought out directory structure for a file based wiki.
Like MVC, but for wikis.

Ideally, it should be so well thought out that people have no problems in deciding where a new page should go.

[jacmoe]

Yes it is really inconvenient to have all files at the root. But that would be to not take advantage of what a flat file wiki can do.

Each directory can be seen as a category. So, let's say that we want to write about security, RBAC in particular.

So we create our new wiki page in the security/rbac dir.

Now, we can easily search the wiki using the address: the http://www.yiiframework.com/wiki/security URL will (once that feature has been implemented) take us to an overview page (an index) - so I venture the claim that it would be much cleaner and more intuitive. :)

[rob006]

Many articles can not be easily assigned to a one specific category, because they cover many aspects at once, so I think it will not work at all. I think more about solution where each article has its own repository (or gist), and we have database with map: slug => github repository Then we can easily have thousands of articles with flat structure and tags (which should work much better than categories), and each article has its own repository, so we don't need to clone and work with one big repository with all wiki articles only for fix typo in one article. It should be more convenient for users, require less work in moderation and accepting all PRs with changes, but probably will make harder to sync wiki with github repositories.

[jacmoe]

Interesting approach. But I would rather have a thousand files in one repo, than a thousand repos :D

The pages can be tagged as people see fit, and new meta data can also be added - not requiring any schema changes. For my site I have meta data for type and for layout and Disqus IDs..

[jacmoe]

As for fixing a typo, people just need to click the edit link, be taken to the Github page where they can hit the edit button and the repo will fork in a second or less. All in the browser. People who have contributed a lot to the wiki can be added as collaborators to ease the burden of maintenance. That would be a pain with a thousand repos I think.

[rob006]

That would be a pain with a thousand repos I think.

Why? For example composer and npm works in that way - create own namespace and use external VCS as data source. Handling GitHub webhooks and force users to use it is the only hard thing. And then you get much more powerful and clean solution - you can use stars from GitHub, issues are assigned to specified article (so you don't have one repository with 2k open issues) and naturally should be handled by article author, so we have less work for moderators. Translating articles should be also much easier - you just forking base repository and pull changes if source article is updated. Besides, one big repository with all content sounds like antipattern - experience shows that separation into a number of smaller projects/repositories is much more convenient.

[samdark]

One repository is better, I think. We can disable issues and wikis to stimulate editing via website. Then it will be the same as current wiki except editing happens at GitHub.

@jacmoe one thing is that old URLs should work as before. And also tags...

[cebe]

even though I like the idea of git based wiki I am quite sure that we do not have the time/resources to build this now. I'd go with porting the existing wiki for now to get the site ready for release (#145). We may switch to a git wiki later if we want to. A migration script has to be written anyway if we do it.

[samdark]

Closing since wiki was already implemented and we're not going to re-do it anytime soon.