diff --git a/README.md b/README.md
index 2d641d7..7ca729c 100644
--- a/README.md
+++ b/README.md
@@ -185,7 +185,7 @@ The most general workspace - is [`Ubuntu-workspace`](./workspaces/ubuntu-workspa
in order to run multiple processes, adds cron, zsh, and other applications that will be used in most workspaces.
Other general workspaces are the [`Base-Workspace`](./workspaces/base-workspace/README.md), which adds several browser-based applications,
-like task scheduler, file browser, documentation framework and workspace own page. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md)
+like task scheduler, file browser, documentation framework and workspace own UI. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md)
adds [Eclipse Theia](https://theia-ide.org/) to the Base-Workspace. Theia - is an open-source browser-based VS-Code version, making
Workspace-in-docker to be a general base workspace, to be used in order to create workspaces for specific tasks (like Python workspace, or
Ansible workspace).
diff --git a/workspaces/codeserver-workspace/README.md b/workspaces/codeserver-workspace/README.md
index bfe1ade..eeed3fd 100644
--- a/workspaces/codeserver-workspace/README.md
+++ b/workspaces/codeserver-workspace/README.md
@@ -4,7 +4,7 @@ General-purpose dockerized workspace - an environment fully isolated inside a do
to file or restored, pushed to docker registry, started on a cloud server.
-
+
#### Try it out
@@ -46,7 +46,7 @@ The Workspace contains browser-based Visual Studio Code, and several browser-bas
-
+
**Tools with UI**
@@ -91,7 +91,7 @@ The IDE is already configured to make code highlighting for many programming lan
-
+
@@ -217,7 +217,7 @@ Open [localhost:8020](http://localhost:8020), and from there open other applicat
-
+
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
@@ -298,7 +298,7 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec
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:
-
+
. Copy this folder to the remote server where you want to launch the Python workspace.
@@ -594,7 +594,7 @@ the new page has appeared in your Workspace UI - it has live reload, and you don
-
+
You can easily build beautiful static website from this documentation
diff --git a/workspaces/mkdocs-magicspace/README.md b/workspaces/mkdocs-magicspace/README.md
index 7cd7507..15af998 100644
--- a/workspaces/mkdocs-magicspace/README.md
+++ b/workspaces/mkdocs-magicspace/README.md
@@ -5,27 +5,33 @@
MkDocs-MagicSpace is an all-in-one tool, carefully crafted to make the development of gorgeous documentation
websites like [**this one**](https://mkdocs-magicspace.alnoda.org/) as easy as possible.
+
+
+
+
+
Try it out:
```
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/mkdocs-magicspace
```
-and open [http://localhost:8020] in browser
+and open [localhost:8020](http://localhost:8020) in browser
## Contents
+* [Why documentation websites with MkDocs](#why-documentation-websites-with-mkdocs)
+* [About](#about)
+* [MkDocs features](#mkdocs-features)
* [Use-cases](#use-cases)
-* [Why documentation websites](#why-documentation-websites)
-* [Features](#features)
-* [The technology behind](#the-technology-behind)
* [Launch Workspace](#launch-workspace)
* [Workspace terminal](#workspace-terminal)
* [Multiple workspaces](#multiple-workspaces)
* [Open more ports](#open-more-ports)
* [Docker in docker](#docker-in-docker)
* [Run on remote server](#run-on-remote-server)
- * [Use Workspace](#use-workspace)
+* [Use Workspace](#use-workspace)
+ * [Create MkDocs website](#create-mkdocs-website)
* [Install applications](#install-applications)
* [Schedule jobs with Cron](#schedule-jobs-with-cron)
* [Python](#python)
@@ -39,30 +45,9 @@ and open [http://localhost:8020] in browser
* [Move workspace to the cloud](#move-workspace-to-the-cloud)
-## Use-cases
+## Why documentation websites with MkDocs
-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
-if it is public or inside the company's VPN.
-
-## Why documentation websites
-
-*Why create separate documentation websites? Why not just write Git readme files?*
+*Why create separate documentation websites? And if so, why MkDocs?*
- MkDocs website with beautiful themes looks much better than any readme file. The resulting documentation website looks professional and awesome.
- MkDocs adds text search to your documentation website.
@@ -72,22 +57,18 @@ if it is public or inside the company's VPN.
can create a unified documentation website from multiple repositories in Github, GitLab, Bitbucket.
- You can add such features as Google Analytics, multi-language localization.
-*And what about Confluent?*
-The approach of having docs in different places (Git repositories, Confluent, Wiki, etc.) has serious drawbacks. It creates chaos, and documentation inevitably diverges with time.
-And you never know where to look for the information you need.
+## About
-The best docs live together with the code. With MkDocs-MagicSpace you can follow this practice with ease, build a documentation website
-from one or many git repositories, include readme files that live close to the code. You can have a build process that even creates
-auto-documentation directly from the code.
+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.
-## Features
+
+ Demo: MkDocs-MagicSpace
+
-MkDocs-MagicSpace has [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) installed with a collection of extensions and plugins
-that bring MkDocs to the next level.
-
-MkDocs-MagicSpace is an extension of the [workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md)
-and has all its features:
+
+
+
- **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
@@ -99,10 +80,23 @@ VS-Code extensions and works in browser. This means it can run inside a docker c
- [**Midnight Commander**](https://midnight-commander.org/) - Feature rich visual file manager with internal text viewer and editor.
- [**Process Monitor**](https://htop.dev/) - Monitor running process and resource utilization.
-Built on top of Base-workspace and Ubuntu-workspace, this workspace gets all the features those workspaces have.
-In particular, workspace-in-docker provides excellent experience when working directly in the terminal, and has docker-in-docker.
+**Other:**
+- Docker in docker
+- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
+- Python 3, Pip
+- Node/nodeenv
+- git, git-flow
+- curl, wget, telnet, jq,
+- nano, vim, mc, ncdu, htop
+- supervisord
+- cron
-#### The technology behind
+Built on top of [Workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md),
+[Base-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/README.md), and
+[Ubuntu-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/ubuntu-workspace/README.md),
+this workspace gets all the features those workspaces have.
+
+#### MkDocs features
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
building project documentation.
@@ -125,6 +119,29 @@ MkDocs-MagicSpace has lots of packages and extensions already installed:
**(The complete list of installed packages - /home/abc/installed-python-packages/mkdocs-requirements.txt)**
+## Use-cases
+
+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
+if it is public or inside the company's VPN.
+
## Launch Workspace
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
@@ -277,25 +294,67 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec
> `python /home/abc/utils/remote.py --workspace="mkdocs-magicspace" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
-**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.
+**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.
-You see folder `/home/abc/utils/remote` is created. Copy this folder to the remote server (any location). Ssh to the server, cd into
-the directory you copied and execute `docker-compose up -d`.
+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:
+
+
+
+
+
+. Copy this folder to the remote server where you want to launch the Python workspace.
+You can use cyberduck or [scp](https://kb.iu.edu/d/agye). ssh to the server, cd to the directory you copied and execute
+
+```sh
+docker-compose up -d
+```
That's it, you workspace is running securely on the remote server, using
-self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace,
-and authentication is added.
+self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace, and authentication is added.
+
+**NOTE:** The HTTPS is with self-signed certificate, and your browser will show a warning, asking you to accept the risk
+
+
+
+
+
+After you accept the risk, authentication window will appear asking you the user and password, that you have set as,
+
+
+
+
+
## Use Workspace
-Among the common actions you'd do in the workspace are
+### Create MkDocs website
+
+[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.
+They are all in one place:
+
+* [Intro](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/intro/)
+* [Basics](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/basics/)
+* [Hack the markdown](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/hack-markdown/)
+* [Improve readability with tabs, lists and footnotes](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/improve-readability/)
+* [Create tables](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/tables/)
+* [Highlight with blockquotes and admonitions](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/highlight-what-matters/)
+* [Make it classy with emoji, icons and more](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/classy-markdown/)
+* [Make images awesome](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/images/)
+* [Add the code](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/add-the-code/)
+* [Write formulas](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/formulas/)
+* [Draw diagrams](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/diagrams/)
+* [Use templates](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/templates-macros/)
+
+In addition you can find here tutorials how to build and deploy your website in just couple of clicks
+* [Build website](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/build-workspace/)
+* [Publish on GitHub Pages](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/github-pages/)
+
-- installation of new applications and runtimes
-- edit files, write code, scripts
-- build, compile and execute code
-- start/stop applications and services
-- schedule tasks and scripts
-- process data
### Install applications
diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-collage.png b/workspaces/mkdocs-magicspace/img/mkdocs-collage.png
new file mode 100644
index 0000000..bc3ec5f
Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-collage.png differ
diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif b/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif
new file mode 100644
index 0000000..7347799
Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif differ
diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif b/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif
new file mode 100644
index 0000000..2ba1153
Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif differ