Open Source documentation for MODX Revolution

I want to present you a new project for maintaining open documentation for MODX Revolution .

What for?

Because the system is far from new, and there is still no normal Russian-language documentation. All that is, scattered across different communities and blogs, which are several dozen, and any novice user runs around, asking questions.

Official documentation in Russian is not conducted. I don’t know how it is now, but a year ago they simply did not have Cyrillic.
')

Why not do it on site n or z?

Because these sites have owners, they need to ask for logins / passwords and there is no guarantee that the site will not disappear tomorrow, leaving your contribution to the Google cache.

For example, I tried to write about my add-ons on the official website, and then they remade it, and my login password no longer works. You just can not register - you need to receive them through a letter of support. Of course, there is no desire to re-do it.

In addition, the MODX community cannot boast of cohesion, and the main developers simply cannot be put together in one place for them to write something.

And what do you suggest?

Very simple - you need to keep documentation in GitHub , in the well-known Markdown format.

Such a system guarantees us:

• The safety of all texts . Each person can copy the repository and host it.
• History of changes . All edits at a glance, you can see who wrote what.
• Independence You can write about any MODX topic in any language. And you do not need to ask for this access - just have an account on GitHub.

The idea is not new, and I peeped it from the project daux.io. This is a php script that generates a site using ready-made markdown files.
It is very simple, and allows you to start your website with documentation, without any skills at all, on any hosting. However, in my opinion, he has several shortcomings (which are a continuation of the merits).

For example, I’m not at all sure that dynamic site generation by file, without caching, will work well on several thousand pages. Also, there is no search, there is no control of the addresses of the pages, convenient switching between language versions, and even trivia.

So, to display our documentation, I used my favorite system - MODX.

How does it work?

This is a regular MODX site, built using standard add-ons, but all of its pages are imported from files.

This gives:

• Caching All documents will be loaded from the cache, and you do not need to wool files on the HDD every time.
• Manage the url of documents - they can be moved without losing the transitions from search engines.
• Ability to organize a search on the site.
• Convenient work with language versions, there may be as many as you like.
• Possibility, in the future, to include on the site authorization (HybridAuth) and comments (Tickets).

There are only documents in the site tree.


I want to keep the possibility of a full update of the tree with pre-cleaning the table, so I generate service pages on the fly and do not save to the database. This is a new notion, let's see how it will work.

For example, a site map is issued like this:

<?php if ($modx->event->name != 'OnHandleRequest' || $modx->context->get('key') == 'mgr') {return;} $alias = $modx->getOption('request_param_alias', null, 'alias'); $request = strtolower($_REQUEST[$alias]); if ($request == 'sitemap.xml') { $output = $modx->runSnippet('pdoSitemap', array('context' => 'web,en')); exit($output); } 

And here are the search pages:

 elseif ($request == 'search') { $doc = $modx->newObject('modResource'); $doc->fromArray(array( 'id' => 100000000, 'context_key' => $modx->context->key, 'pagetitle' => $modx->context->key == 'en' ? 'Search' : '', 'template' => 3, 'content' => ' [[!pdoPage@Search?context=`'.$modx->context->key.'`]] [[+page.nav]] ' )); $modx->resource = $doc; $response = $modx->getResponse(); $output = $modx->response->outputContent(); exit($output); } 

That is, the work goes through a plugin for the OnHandleRequest event and depends on the context (language version).

I sketched the layout on Bootstrap 3 so that it was comfortable to read from phones and tablets. For work are used:

• pdoTools - output neighboring documents, all menus and breadcrumbs.
• mSearch2 - morphological search.
• DateAgo - nice date format
• yTranslit - generation of url pages through Yandex translations.
• MinifyX - gluing and compressing scripts and styles for fast loading pages.
• Markdown is a new snippet for outputting texts in this format. Posted specifically for this project.

Once again I remind you that this documentation does not belong to anyone . I made my version of the site for its withdrawal, and you can clone the repository and run it on the same daux.io - the directory and file structure is compatible.

The goal of the project is to finally give the community a tool to collect all the information in one place and use it together. Join now !

Links

Documentation repository on gitub.
Site with the output of this documentation.

Future plans: developing a simple API for displaying texts on other sites and (possibly) abbreviation url.

Updated January 15, 2014

Due to dissatisfaction with the domain name, the documentation was moved to docs.modx.pro .

I hope there will be no more objections.