- In the case of closed-source software, sharing readme files from the git repository with external users is not an option.
- Github does not render beautiful extended markdown features like admonitions, tabs, etc. Neither renders diagrams, formulas, swagger docs, or notebooks.
The Workspace contains browser-based Visual Studio Code, and several browser-based tools that make it more convenient to work from inside a docker container.
- **Workspace UI** - launch all workspace tools from one place.
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/Cronicle) - task scheduler and runner, with a web based front-end UI. It handles both scheduled, repeating and on-demand jobs, targeting any number of worker servers, with real-time stats and live log viewer.
- [**Static File Server**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
MkDocs-MagicSpace in its essense is all about [**MkDocs**](https://www.mkdocs.org/) - a fast, simple and downright gorgeous static site generator that's geared towards
MkDocs has many themes, MkDocs-MagicSpace has [**Material for MkDocs**](https://squidfunk.github.io/mkdocs-material/) set up and configured by default.
It is one of the best themes for MkDocs, which makes your website look very professional. This theme is extremely customizable,
searchable, mobile-friendly, has 40+ languages, has built-in search. It also adds lots of markdown features such as tabbed content containers, mathematical formulas, critic markup,
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) - add even more cool features of the extended markdown: sub- and superscripts, keys, magic links, sane headers etc.
- [Mkdocs-macro plugin](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) - add variables and macros written in Python!
- [Mkdocs-monorepo plugin](https://backstage.github.io/mkdocs-monorepo-plugin/) - build multiple documentation folders in a single Mkdocs. Designed for large codebases.
- [MkDocs Newsletter](https://lyz-code.github.io/mkdocs-newsletter/) - show the changes of documentation repositories in a user friendly format, at the same time that it's easy for the authors to maintain.
- [Mkdocs-mermaid2-plugin](https://github.com/fralau/mkdocs-mermaid2-plugin) - renders textual graph descriptions into Mermaid graphs (flow charts, sequence diagrams, pie charts, etc.).
- [Pygments](https://pygments.org/) - a generic syntax highlighter suitable for use in code hosting, forums, wikis or other applications that need to prettify source code, with over 500 languages and other text formats.
- [Mkdocs-include-markdown-plugin](https://github.com/mondeja/mkdocs-include-markdown-plugin) - include Markdown files completely or partially, and include files of any type.
- [Mkdocs-table-reader-plugin]() - directly insert CSV files as tables in your website.
This workspace has many tools and dependencies, configuring it from scratch will cost you a lot of time.
With the help of MkDocs-MagicSpace you can develop, build and serve the following kinds of websites:
1. Awesome looking docs for your open-source project. Use HTML & CSS to create front page and markdown for doc pages.
2. User manuals and API docs. While enterprise docs are for internal use, create great-looking API websites for your users, and manuals for your customers.
1. Enterprise documentation websites that unite numerous git repositories into one documentation project.
4. Tutorials and training websites. Do you have a lot of experience in something? Share it with the world.
MkDocs-MagicSpace helps you to highlight the code in many programming languages, write complex mathematical formulas,
[draw diagrams]((https://mermaid-js.github.io/mermaid/#/)) and so much more!
5. With MkDocs-MagicSpace you can also create books, booklets, and brochures as .pdf files.
One of the most convenient features of the MkDocs-MagicSpace - is that it is a workspace in docker.
You use it on your local machine, you can run it on the remote server and collaborate with your colleagues,
you can give it to your peer as a whole. And you can use it to serve your docs from any server, no matter
This way allows to ssh into the workspace as a root user at any time, even if the workspace itself was not starter as root user (the default user is abc)
Because workspace is just a docker image, running it in any other server is as easy as running it on local laptop.
Running on remote server makes it much simpler to collaborate, because you can just share credentials to the workspace with your peers, and they will be able to use it.
You can also run applications that should run permanently, and run jobs on schedule.
#### Unsecure remote workspace
The simplest deployment of the workkspace requires only 3 steps:
This way launches workspace in cloud, but such workspace is not secure, everyone who knows IP of your server will be able to use it.
#### Secure remote workspace
*You might want to restrict access to the workspace, and secure encrypted communication with the workspace*
Kkdocs-MagicSpace contains utility that will generate everything needed to launch the workspace in cloud in a secure way, with authentication and with TLS.
If you want to run workspace on the remote server securely, start mkdocs-magicspace on your local laptop first, open its terminal and
use utility `/home/abc/utils/remote.py` to generate create docker-compose project with TLS certificates. Simply execute
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
After you accept the risk, authentication window will appear asking you the user and password, that you have set as<ANY_USER_NAME>, <ANY_USER_PASSWORD>
[MkDocs](https://www.mkdocs.org/) is very powerful. Even more powerful it becomes with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
But this workspace takes it to the space by having tons of Markdown plugins carefully selected, configured, and set up. It would be impossible to
demonstrate all of the advanced Markdown features in the Readme file, simply because standard engines that render Markdown do not support the
advanced features.
We have prepared extended Markdown tutorials, so that you don't need to search in the Internet for docs of every Markdown plugin.
| | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
| | | | |
** ** * command to be executed
```
**NOTE** you can disconnect from the image and close terminal - cron will continue working.
> Instead of cron you might want to use Cronicle - a tool with Web UI, and a great list of features
> that will provide you with the dashboard, list of executions and statistics, even let you ser limis
> on resources for each jobs, and create depenndencies between jobs.
### Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python`
install python package with pip, for
> `pip install pandas`
If you are planning to work with python, we recommend to install IPython, that provides a rich toolkit to help
you make the most of using Python interactively. Install and start ipython
> ```pip install ipython```
> `ipython`
### Node.js
We recommend to use nodeenv to create different node environments.
For example, open workspace terminal, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
> `cd /home`
> `mkdir npmgui; cd npmgui`
> `nodeenv --node=12.18.3 --npm=6.0.0 env`
Let's install package and start node application
> `. env/bin/activate && npm i -g npm-gui`
> `npm-gui 0.0.0.0:8030`
Open your browser on http://localhost:8030/
**NOTE:** If you close terminal, the application will stop. See how to [start applications that reamin live after closing a workspace terminal](#run-applications-and-services-inside-the-workspace)
### Run applications and services inside the workspace
If you want application to keep running after workspace terminal is closed start it with **"&!"** at the end.
For example, in the last section we started *npm-gui* tool with command `npm-gui 0.0.0.0:8030`. If you close the workspace terminal,
this application witll stop running. To keep it running after terminal is closed, execute
> `npm-gui 0.0.0.0:8030 &!`
Now, if you disconnect from the workspace and close terminal, the application will continue running in the workspace, untill [workspace is stopped](#start-and-stop-workspaces).
A better way to manage images is docker registries. You can use docker registries in multiple clouds. They are cheap annd very convenient.
Check out for example, [Registry in DigitalOcean](https://www.digitalocean.com/products/container-registry/) or in [Scaleway container registry](https://www.scaleway.com/en/container-registry/). There are more.
Pushing image to registry is merely 2 extra commands: 1) tag image; 2) push image
You will be able to pull image on any device, local or cloud.