McDao - MarkDown with accent
The question of the content management method (in its narrow technical sense, how exactly the content editor manages the data) stood for me a long time ago. Many years of development experience has shown that there is no definite answer, and there will not be. There are a lot of dependencies on a specific task, technical training for managers and other factors. The decision on which methodology will be applied in the system will be different in each case.
But at least it was possible to identify some unambiguous elements. For example, the invincible truth arose the thesis: "WYSIWIG is an absolute evil." This refers to WYSIWIG general editors like TinyMCE and the like. Below we will touch upon the "limiting" editors as one of the permissible evils.
What is the main problem with WYSIWIG? No one will ever force the editor to adhere to the developed single style of the site. He (a) will always find an excuse for himself, why the background here is poisonous yellow, and there the title is pink. For the most part, this is not a problem, let the site owner enjoy his work. The problem begins when a team arrives to update the design of the entire site. Caps, menus, basement, of course, we will change, but what to do with the content? Even if the spherical manager in the vacuum strictly adhered to the recommendations of the designer, all the same about the HTML code generated by the WYSIWIG editor, a lot of teeth would break.
')
As one of the outputs, you can use special WYSIWIG editors, where almost all the possibilities are cut off, except for the styles that the designer provided for in this project. Accordingly, the HTML code will be generated quite “clean”. Such a solution is applicable, for example, when a potential editorial contingent is incorrigibly blond.
However, even “limiting” WYSIWIG editors are not ideal. There are at least two reasons for this. First of all, not all content elements manage for WYSIWIG. Here and there, we have to arrange conditional markers to insert gadgets and other non-standard elements. In some projects there are so many of them that the question arises: “For what did you fight? Isn't it easier then to mark all the content? ”
The second reason for not using even “limiting” WYSIWIG is that they have to add a lot of code to them in the form of image managers, styles, gadgets, etc. And even if it seems that everything is provided for, it turns out that something is missing or inconvenient, or not as we need in this project. What are we doing in essence? We create inconvenient angular bicycles, replacing the old, well-known familiar file managers, browsers and other elements of the operating system.
Try to reduce the number of degrees of freedom. Suppose that our managers are computer literate people. They know what a file is, what a web page with its address is, they know how to distinguish the picture on their drive from the picture on the Internet. Such WYSIWIGs with their poor means are more expensive to keep on a tight leash. They need to be provided with a convenient and laconic labeling system and released to float freely.
The choice of marking is not really great. HTML definitely disappears. And not because of some mythical “danger” (firstly, filtering it is not difficult in our day, and secondly, why filter the input from a moderator / manager / site owner altogether). The main reason is that HTML is too verbose. For example, to create such a very typical element as a picture with a sub-title, you need to write a decent bunch of code. It is not entirely correct to make such managers even copy-paste. You can extend the HTML standard for this particular project and add additional tags and attributes. But in general, it all looks very untidy.
The second alternative is BB codes. In essence, this is the very HTML extension that is mentioned in the previous paragraph. And according to this untidiness remains. In addition, illegality. Text with BB codes is very difficult to read. Perhaps due to the fact that the square brackets merge too well with the letters, unlike, say, the same angle brackets. I consider WYSIWIG editors generating BB codes a bad joke.
Finally we got to the essence of the article. Yes, that last version of MarkDown. Overall, MarkDown creates a good impression. He is laconic, mnemonic, well perceived visually. There are some flaws, such as limited vocabulary and inconsistencies in dialects. Actually these questions and is intended to solve McDao .
McDao (pronounced “mecdao”) is a MarkDown markup parser library written in PHP and intended to be embedded in content management systems. The main feature of McDao is extensibility. You can enter your markers from any characters or their combinations, as well as override the standard markers. In addition, introduced a unified syntax for marker detailing. This primarily concerns such more complex elements as pictures or links. From Vikipedovskoy like brackets a little nauseated. There is no problem for the part-time editor of Wikipedia, but for any other lay person these piles of brackets are never mnemonic.
This detailing syntax also applies to any other standard or predefined marker, not just links and images. I do not claim that this syntax is an example of mnemonicity, but nevertheless it is good in that it is compatible with all markers, and as you will see, it is not exotic at all.
McDao implies two entities: a paragraph, separated from the other by at least one empty line, and inline text. Actually there is nothing new here, we simply state this rule. The first non-alphanumeric character (or several characters), separated from the rest of the text by a space, is the control for this paragraph. You don’t have to write anything special about the inline text, everyone is perfectly familiar with its use. All this can be illustrated as follows:
Familiar, is not it? Now for a more subtle question - square brackets. By default, we gave them entirely to only the pictures [picture.jpg]. And what got to the links? You would never guess: _www.example.com_. But what about the usual underscore? Well, firstly, in a good stylish and practical design there is no place for ordinary underlining. And secondly, if the parser finds that it is not the link that came across to it, then it will underline this text.
Now the very grain of the McDao dialect, as we introduce additional attributes to the markers. To do this, use angle brackets like this: [picture] <picture.jpg> and like this: _example_ <www.example.com>. Why is this data so distributed? We use the following rule and recommend that you define your custom markers: everything that the viewer sees (or potentially sees) is written inside the marker, and the technical off-screen attributes are placed in angle brackets. Formally, using this rule, if you do not specify the ALT attribute for a picture, then you need to write [] <picture.jpg>. Yes, you can and so. But why does it need a pivot where it is not necessary, and where the parser will deal with [picture.jpg] perfectly. We initially set ourselves the goal of conciseness and friendliness of syntax.
Now a more complex example: a picture with a link. Correctly suggest from the second row, you must use _ [] _. However, there are quite a few additional attributes. One of the options to deal with them:
But agree, rather clumsily. Isn't it better to simply define a new two-character special marker, which we did:
As you noticed, if there are more than one additional attributes, then they should be named. This example is purely academic. In real life, it will look much simpler:
With a well-thought-out approach, the need for named attributes should be extremely rare.
No sane developer will not allow to specify absolute addresses on the internal pages of the site. And even something like
unacceptable, because there may be CNC and much more. This is where the interception of markers comes to the rescue. The internal address can be written in any conditional syntax that will be parsed and in its place will substitute what you need. For example:
For some gadgets, you can define special markers. For example, we need to insert a video. We select for the video marker curly brackets. It turns out something like this: {j76JvlLbki45c}. All the ugly longs and the full path to youtube are hidden from the content manager by a caring developer.
And we also need to insert text blocks or modules on the page. Type include ... What would we come up with such a mnemonic? Well, let's say, for example, that the news module here will look like this: {+ news +}. Do not be embarrassed that the braces are already involved under the video, everything will be processed correctly. Although it should be noted, in this case it would be better to define the video as something like {[video.flv]} for mnemonicity and consistency.
It works the same way with paragraph markers:
McDao allows you to create fairly complex overrides. Here is one of the typical tasks: to define a list of articles. The elements of the list are: title, link, icon, introductory text (teaser). Here is how McDao coped with this task (after setting several additional rules):
As you can see, we have entered a special marker “-” to define an element of our extended list. And all other definitions are quite readable and obvious.
Standard default behavior McDao provides for the following markers:
Predefined (but redefinable) inline markers:
I will not go into the technical details on how to use this library. Whom she interested will be able to download and understand. In general, the library is quite lightweight. However, the caching of the results of its work has not yet been prevented by anyone (caching is not within the scope of McDao and is vested in the CMS).
It should be noted another unexpected side of the application of McDao . In one of our projects, it was necessary to store and periodically edit the data of a rather complex structure. Formally, the most suitable for this is XML. However, this respected syntax, developed as human readable, in fact proved to be too verbose and very unreadable. In principle, there is a lot more pleasant YAML. However, it turned out that McDao can be used for this purpose (with a set of redefined rules). It even gave some advantages. Firstly, managers are already familiar with its syntax, and secondly, the mnemonicity, designed specifically for a specific task, gave odds to even the convenience of YAML.
Such is McDao , which will undoubtedly arouse the interest of MarkDawn connoisseurs and those who are looking for a convenient solution in content management, where almost unlimited flexibility is needed in combination with brevity and simplicity.
But at least it was possible to identify some unambiguous elements. For example, the invincible truth arose the thesis: "WYSIWIG is an absolute evil." This refers to WYSIWIG general editors like TinyMCE and the like. Below we will touch upon the "limiting" editors as one of the permissible evils.
What is the main problem with WYSIWIG? No one will ever force the editor to adhere to the developed single style of the site. He (a) will always find an excuse for himself, why the background here is poisonous yellow, and there the title is pink. For the most part, this is not a problem, let the site owner enjoy his work. The problem begins when a team arrives to update the design of the entire site. Caps, menus, basement, of course, we will change, but what to do with the content? Even if the spherical manager in the vacuum strictly adhered to the recommendations of the designer, all the same about the HTML code generated by the WYSIWIG editor, a lot of teeth would break.
')
As one of the outputs, you can use special WYSIWIG editors, where almost all the possibilities are cut off, except for the styles that the designer provided for in this project. Accordingly, the HTML code will be generated quite “clean”. Such a solution is applicable, for example, when a potential editorial contingent is incorrigibly blond.
However, even “limiting” WYSIWIG editors are not ideal. There are at least two reasons for this. First of all, not all content elements manage for WYSIWIG. Here and there, we have to arrange conditional markers to insert gadgets and other non-standard elements. In some projects there are so many of them that the question arises: “For what did you fight? Isn't it easier then to mark all the content? ”
The second reason for not using even “limiting” WYSIWIG is that they have to add a lot of code to them in the form of image managers, styles, gadgets, etc. And even if it seems that everything is provided for, it turns out that something is missing or inconvenient, or not as we need in this project. What are we doing in essence? We create inconvenient angular bicycles, replacing the old, well-known familiar file managers, browsers and other elements of the operating system.
Try to reduce the number of degrees of freedom. Suppose that our managers are computer literate people. They know what a file is, what a web page with its address is, they know how to distinguish the picture on their drive from the picture on the Internet. Such WYSIWIGs with their poor means are more expensive to keep on a tight leash. They need to be provided with a convenient and laconic labeling system and released to float freely.
The choice of marking is not really great. HTML definitely disappears. And not because of some mythical “danger” (firstly, filtering it is not difficult in our day, and secondly, why filter the input from a moderator / manager / site owner altogether). The main reason is that HTML is too verbose. For example, to create such a very typical element as a picture with a sub-title, you need to write a decent bunch of code. It is not entirely correct to make such managers even copy-paste. You can extend the HTML standard for this particular project and add additional tags and attributes. But in general, it all looks very untidy.
The second alternative is BB codes. In essence, this is the very HTML extension that is mentioned in the previous paragraph. And according to this untidiness remains. In addition, illegality. Text with BB codes is very difficult to read. Perhaps due to the fact that the square brackets merge too well with the letters, unlike, say, the same angle brackets. I consider WYSIWIG editors generating BB codes a bad joke.
Finally we got to the essence of the article. Yes, that last version of MarkDown. Overall, MarkDown creates a good impression. He is laconic, mnemonic, well perceived visually. There are some flaws, such as limited vocabulary and inconsistencies in dialects. Actually these questions and is intended to solve McDao .
McDao (pronounced “mecdao”) is a MarkDown markup parser library written in PHP and intended to be embedded in content management systems. The main feature of McDao is extensibility. You can enter your markers from any characters or their combinations, as well as override the standard markers. In addition, introduced a unified syntax for marker detailing. This primarily concerns such more complex elements as pictures or links. From Vikipedovskoy like brackets a little nauseated. There is no problem for the part-time editor of Wikipedia, but for any other lay person these piles of brackets are never mnemonic.
This detailing syntax also applies to any other standard or predefined marker, not just links and images. I do not claim that this syntax is an example of mnemonicity, but nevertheless it is good in that it is compatible with all markers, and as you will see, it is not exotic at all.
McDao implies two entities: a paragraph, separated from the other by at least one empty line, and inline text. Actually there is nothing new here, we simply state this rule. The first non-alphanumeric character (or several characters), separated from the rest of the text by a space, is the control for this paragraph. You don’t have to write anything special about the inline text, everyone is perfectly familiar with its use. All this can be illustrated as follows:
= =
== ==
** .
Familiar, is not it? Now for a more subtle question - square brackets. By default, we gave them entirely to only the pictures [picture.jpg]. And what got to the links? You would never guess: _www.example.com_. But what about the usual underscore? Well, firstly, in a good stylish and practical design there is no place for ordinary underlining. And secondly, if the parser finds that it is not the link that came across to it, then it will underline this text.
Now the very grain of the McDao dialect, as we introduce additional attributes to the markers. To do this, use angle brackets like this: [picture] <picture.jpg> and like this: _example_ <www.example.com>. Why is this data so distributed? We use the following rule and recommend that you define your custom markers: everything that the viewer sees (or potentially sees) is written inside the marker, and the technical off-screen attributes are placed in angle brackets. Formally, using this rule, if you do not specify the ALT attribute for a picture, then you need to write [] <picture.jpg>. Yes, you can and so. But why does it need a pivot where it is not necessary, and where the parser will deal with [picture.jpg] perfectly. We initially set ourselves the goal of conciseness and friendliness of syntax.
Now a more complex example: a picture with a link. Correctly suggest from the second row, you must use _ [] _. However, there are quite a few additional attributes. One of the options to deal with them:
_[alt ]<picture.jpg>_<address>
But agree, rather clumsily. Isn't it better to simply define a new two-character special marker, which we did:
_[alt ]_<src=picture.jpg href=address>
As you noticed, if there are more than one additional attributes, then they should be named. This example is purely academic. In real life, it will look much simpler:
_[picture.jpg]_<address>
With a well-thought-out approach, the need for named attributes should be extremely rare.
No sane developer will not allow to specify absolute addresses on the internal pages of the site. And even something like
_ _<index.php?page=contact>
unacceptable, because there may be CNC and much more. This is where the interception of markers comes to the rescue. The internal address can be written in any conditional syntax that will be parsed and in its place will substitute what you need. For example:
_ _<contact>
_ _<price,alpha>
For some gadgets, you can define special markers. For example, we need to insert a video. We select for the video marker curly brackets. It turns out something like this: {j76JvlLbki45c}. All the ugly longs and the full path to youtube are hidden from the content manager by a caring developer.
And we also need to insert text blocks or modules on the page. Type include ... What would we come up with such a mnemonic? Well, let's say, for example, that the news module here will look like this: {+ news +}. Do not be embarrassed that the braces are already involved under the video, everything will be processed correctly. Although it should be noted, in this case it would be better to define the video as something like {[video.flv]} for mnemonicity and consistency.
It works the same way with paragraph markers:
= - <special>
.
,
.<foobar>
%
«».
:
% {j76JvlLbki45c}
McDao allows you to create fairly complex overrides. Here is one of the typical tasks: to define a list of articles. The elements of the list are: title, link, icon, introductory text (teaser). Here is how McDao coped with this task (after setting several additional rules):
-- 1 [icon1.gif]<link1>
Introduction text blah-blah-blah…
-- 2 [icon2.gif]<link2>
Another introduction text blah-blah-blah…
As you can see, we have entered a special marker “-” to define an element of our extended list. And all other definitions are quite readable and obvious.
Standard default behavior McDao provides for the following markers:
= =
== ==
===
--- ( )
-
-
-
#
#
> «>»
>
|= 1 =|= 2 =|= 3 =|
| | | |
| | | |
| | xxx | |
. <p>.
<script>
/* , HTML , */
</script>
Predefined (but redefinable) inline markers:
**
//
^ ^
_ _
[]
_[ ]_
I will not go into the technical details on how to use this library. Whom she interested will be able to download and understand. In general, the library is quite lightweight. However, the caching of the results of its work has not yet been prevented by anyone (caching is not within the scope of McDao and is vested in the CMS).
It should be noted another unexpected side of the application of McDao . In one of our projects, it was necessary to store and periodically edit the data of a rather complex structure. Formally, the most suitable for this is XML. However, this respected syntax, developed as human readable, in fact proved to be too verbose and very unreadable. In principle, there is a lot more pleasant YAML. However, it turned out that McDao can be used for this purpose (with a set of redefined rules). It even gave some advantages. Firstly, managers are already familiar with its syntax, and secondly, the mnemonicity, designed specifically for a specific task, gave odds to even the convenience of YAML.
Such is McDao , which will undoubtedly arouse the interest of MarkDawn connoisseurs and those who are looking for a convenient solution in content management, where almost unlimited flexibility is needed in combination with brevity and simplicity.
Source: https://habr.com/ru/post/118938/
All Articles