A prototype of an unusual add-on for GitHub, a web-help preparation system using GitHub Pages
Continuing my risky and inhuman experiments in the field of web design, today I bring to your attention the further development of Markdown webdocs and its integration with the GitHub service.
What turned out: quite simple, several wiki-like (in the approach to editing), with markdown + html + text formatting components, with a built-in editor (and not only the page text, but also the site structure), without additional services / servers / database based on Git (Hub) and files, in fact, a CMS system focused on creating documentation, simple sites or web applications, with the possibility of distributed work with a common repository (readable diffs, automatic commits, pool-requests are possible).
If you use this service, then you most likely know this feature, GitHub provides each user with the opportunity to create a third-level website in * .imtqy.com absolutely free of charge, provided that materials are posted on it under one of the open licenses. If we write reference materials, we can easily publish them under an open license (for example, Artistic License 2.0) and use the free GitHub Pages service to publish them.
By default, GitHub provides you with just a few clicks to create a static site with a good design. And it works great if you need one page with two buttons. However, if you want to create a website with more pages, and even give it the opportunity to complement third-party people, it is not so convenient. Here there is a need for some CMS, we begin to sort out the options. I want to edit the text, not the html code. And do not want to once again communicate with various complex systems or external services. Which system would be justified when publishing one page of text with pictures, would allow creating complex documentation without changing technology and would not be restricted to use on different platforms?
I asked myself the question whether it is possible to create a CMS that would allow editing pages on-line as wikipedia and would work with files through Git, without an additional backend server and a separate database. After a bit of research, it turned out that the GitHub web-API provides all the possibilities for this, it was necessary only to create the corresponding web interface. Today, a fully working prototype of such a system is ready, with which you can play to the fullest.
')
Creating your own site on Markdown webdocs is simple; you need to do three things:
1) Go to the repository at this address github.com/aplib/docs-ru and fork it with the Fork button in the right-top corner.
A fork of docs-ru will appear among your repositories and after a while (no more than ten minutes), it will become available through GitHub Pages for viewing by the browser at your personal address on username.imtqy.com. That is, you automatically create a copy of my site and publish it online. You can see the link to your site in the Settings section of your fork (Settings at the bottom right in the repository view window). If the site does not appear for a long time, you can speed up by changing some file in the repository and creating the first commit.
2) In order to enable online editing and creating new pages on your site, create another repository in your account named username.imtqy.com (instead of username, you need to substitute your nickname on GitHub, in the example this is veensun.imtqy.com ), and copy files into it from the subfolder /username.imtqy.com
3) Using a Personal Access Token instead of a password will be safer when sending pages to GitHub. You can get it here at github.com/settings/applications . The token has the ability to configure access rights, with its help (even if it was taken away), you cannot change passwords, you cannot delete the repository or destroy your account. And at any time you can cancel the current or create a new token.
Go to the page, you can open the on-line editor by Ctrl + F12 or by clicking on the link “edit this page”
Then go to the bookmark (for example) "content-panel" in the editor and enter a new text. When you edit a page, the changes are automatically saved locally in the browser. You can write changes to the repository by clicking the GitHub button in the online editor, a commit will be automatically created with the changes made. After you have made changes and created a commit, the changes are visible on your version of the site in a dozen or two seconds.
You can create pages by typing their address in the address bar of the browser. The address of the page in the address bar of the browser can end with the extension .html, can be typed without .html, both options will be correct. For example, I can type in the address bar aplib.imtqy.com/docs-ru/test (of course you will have a slightly different link to your repository or fork). On the opened service page there will be a button “Create a page”, click it and just wait for our new page to appear, after which we can start editing it.
After you have made changes, you can open your fork page on github.com and send a pull-request these changes to the original repository from which the fork was created. Thus, several users can absolutely safely work with common documents. (Please do not send me pool requests of your experiments, otherwise I will have a local habr effect)
The documentation created using this technology can be edited in a local repository clone and compiled into ready-made HTML, whose pages will load faster. To do this, in the local repository clone on your computer, open the page for viewing using node-webkit, open the built-in editor and resave the page in the compiled form ".html + .mw.html"
A small note: on the Markdown webdocs system, if you create or edit pages locally, then do not forget to correctly assign the root and src attributes to the script tag connecting the document.min.js library. “Root” (optional) is a relative path to the root folder of the site / library and is needed for proper link building, “src” is a relative path to the library file.
For search robots, it is enough to create at least one page compiled in HTML (saved as .html + .mw.html), containing the internal links of the site and having external incoming links.
Markdown webdocs is more than just markdown, it is an extensible markup language. Examples of components on the home site of the project aplib.imtqy.com/markdown-site-template , to use them, you need to copy the site folder into the components.
Technically, of course I have something to criticize, but not yet. Some things are due to the recent start of the project and will be corrected later.
Try, ask questions, all contacts are published in the profile. Or write questions and opinions there github.com/aplib/docs-ru/issues (in Russian).
What turned out: quite simple, several wiki-like (in the approach to editing), with markdown + html + text formatting components, with a built-in editor (and not only the page text, but also the site structure), without additional services / servers / database based on Git (Hub) and files, in fact, a CMS system focused on creating documentation, simple sites or web applications, with the possibility of distributed work with a common repository (readable diffs, automatic commits, pool-requests are possible).
If you use this service, then you most likely know this feature, GitHub provides each user with the opportunity to create a third-level website in * .imtqy.com absolutely free of charge, provided that materials are posted on it under one of the open licenses. If we write reference materials, we can easily publish them under an open license (for example, Artistic License 2.0) and use the free GitHub Pages service to publish them.
By default, GitHub provides you with just a few clicks to create a static site with a good design. And it works great if you need one page with two buttons. However, if you want to create a website with more pages, and even give it the opportunity to complement third-party people, it is not so convenient. Here there is a need for some CMS, we begin to sort out the options. I want to edit the text, not the html code. And do not want to once again communicate with various complex systems or external services. Which system would be justified when publishing one page of text with pictures, would allow creating complex documentation without changing technology and would not be restricted to use on different platforms?
I asked myself the question whether it is possible to create a CMS that would allow editing pages on-line as wikipedia and would work with files through Git, without an additional backend server and a separate database. After a bit of research, it turned out that the GitHub web-API provides all the possibilities for this, it was necessary only to create the corresponding web interface. Today, a fully working prototype of such a system is ready, with which you can play to the fullest.
')
Instructions how to read this
Creating your own site on Markdown webdocs is simple; you need to do three things:
1) Go to the repository at this address github.com/aplib/docs-ru and fork it with the Fork button in the right-top corner.
A fork of docs-ru will appear among your repositories and after a while (no more than ten minutes), it will become available through GitHub Pages for viewing by the browser at your personal address on username.imtqy.com. That is, you automatically create a copy of my site and publish it online. You can see the link to your site in the Settings section of your fork (Settings at the bottom right in the repository view window). If the site does not appear for a long time, you can speed up by changing some file in the repository and creating the first commit.
2) In order to enable online editing and creating new pages on your site, create another repository in your account named username.imtqy.com (instead of username, you need to substitute your nickname on GitHub, in the example this is veensun.imtqy.com ), and copy files into it from the subfolder /username.imtqy.com
3) Using a Personal Access Token instead of a password will be safer when sending pages to GitHub. You can get it here at github.com/settings/applications . The token has the ability to configure access rights, with its help (even if it was taken away), you cannot change passwords, you cannot delete the repository or destroy your account. And at any time you can cancel the current or create a new token.
Editing an existing page
Go to the page, you can open the on-line editor by Ctrl + F12 or by clicking on the link “edit this page”
Then go to the bookmark (for example) "content-panel" in the editor and enter a new text. When you edit a page, the changes are automatically saved locally in the browser. You can write changes to the repository by clicking the GitHub button in the online editor, a commit will be automatically created with the changes made. After you have made changes and created a commit, the changes are visible on your version of the site in a dozen or two seconds.
Creating a new page
You can create pages by typing their address in the address bar of the browser. The address of the page in the address bar of the browser can end with the extension .html, can be typed without .html, both options will be correct. For example, I can type in the address bar aplib.imtqy.com/docs-ru/test (of course you will have a slightly different link to your repository or fork). On the opened service page there will be a button “Create a page”, click it and just wait for our new page to appear, after which we can start editing it.
After you have made changes, you can open your fork page on github.com and send a pull-request these changes to the original repository from which the fork was created. Thus, several users can absolutely safely work with common documents. (Please do not send me pool requests of your experiments, otherwise I will have a local habr effect)
Work locally and compile to HTML
The documentation created using this technology can be edited in a local repository clone and compiled into ready-made HTML, whose pages will load faster. To do this, in the local repository clone on your computer, open the page for viewing using node-webkit, open the built-in editor and resave the page in the compiled form ".html + .mw.html"
A small note: on the Markdown webdocs system, if you create or edit pages locally, then do not forget to correctly assign the root and src attributes to the script tag connecting the document.min.js library. “Root” (optional) is a relative path to the root folder of the site / library and is needed for proper link building, “src” is a relative path to the library file.
Search Engine Indexing
For search robots, it is enough to create at least one page compiled in HTML (saved as .html + .mw.html), containing the internal links of the site and having external incoming links.
* * *
An example of the site aplib.imtqy.com/docs-ru created in this wayMarkdown webdocs is more than just markdown, it is an extensible markup language. Examples of components on the home site of the project aplib.imtqy.com/markdown-site-template , to use them, you need to copy the site folder into the components.
Technically, of course I have something to criticize, but not yet. Some things are due to the recent start of the project and will be corrected later.
Try, ask questions, all contacts are published in the profile. Or write questions and opinions there github.com/aplib/docs-ru/issues (in Russian).
* * *
Upd: It turned out that immediately after the fork was made, / doc-ru / * on your site may be unavailable until the first commit has been made. Therefore, you need to go to the repository and make some minor change. In the future, this feature will be taken into account in the installer.Source: https://habr.com/ru/post/205364/
All Articles