{"id":28003260,"url":"https://github.com/caiorss/mwiki","last_synced_at":"2025-07-31T13:39:42.089Z","repository":{"id":271976217,"uuid":"914587308","full_name":"caiorss/mwiki","owner":"caiorss","description":"Math-oriented Wiki engine for scientific and technical communication based on MyST Markdown, GFM (Github-Flavored Markdown), Obsidian Markdown and Media Wiki markup language.","archived":false,"fork":false,"pushed_at":"2025-05-07T13:18:59.000Z","size":14388,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-09T02:00:03.564Z","etag":null,"topics":["cms","markdown","math","myst","obsidian","scientific","technical","wiki"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caiorss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-09T22:21:43.000Z","updated_at":"2025-05-07T13:19:02.000Z","dependencies_parsed_at":"2025-04-27T00:29:12.143Z","dependency_job_id":null,"html_url":"https://github.com/caiorss/mwiki","commit_stats":null,"previous_names":["caiorss/mwiki"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiorss%2Fmwiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiorss%2Fmwiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiorss%2Fmwiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiorss%2Fmwiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiorss","download_url":"https://codeload.github.com/caiorss/mwiki/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253176434,"owners_count":21866142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cms","markdown","math","myst","obsidian","scientific","technical","wiki"],"created_at":"2025-05-09T02:00:10.402Z","updated_at":"2025-07-31T13:39:42.071Z","avatar_url":"https://github.com/caiorss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MWiki - Markdown-Powered Wiki \n\n## Overview \n\nMWiki is a **wiki engine** and note taking web application software geared towards mathematics and research designed for scientific and technical communication. This wiki engine software has semantic-rich lightweight markup language based on MyST markdown, Obsidian markdown, and Media wiki engine markup language. \n\nThis Python application is powered by Python Flask web framework and the extensible markdown-it parser used by MyST markdown and the Jupyter Book project. \n\nApplications:\n+ Documentation \n+ Technical/Scientific Writing, specially STEM (Science, technology, engineering, and mathematics) fields.\n+ Personal Knowledge Base\n+ Knowledge and Information Preservation \n\n\nNOTES: \n\n+ Note: This software is still **work in progress** and under early stage. However, it can already be used as a personal note taking application.\n+ Note: Mediawiki is the wiki engine software that powers Wikipedia.\n\nSee also:\n\n+ [README in Portuguese](./README-portuguese.md) - Portuguese language version of this document. The original documentation was written in English.\n\n\n### Features Highlights\n\n#### Wiki Features \n\n+ File-based Wiki: all Wiki pages are stored as Markdown files like Moin Moin wiki engine and Dokuwiki. However, it uses SQLite file database or a any full-featured database for system management purposes. \n + Supports MyST Markdown, GFM (Github-Flavored Markdown Support), subset of Obsidian Markdown syntax, subset of Mediawiki markup language and inline HTML.\n + Pages written in Markdown-based markup language instead of HTML, which allows to any non programmers to write scientific and technical documents that are rendered to html. \n + Buttons for editing specific document sections similar to Media wiki section editing buttons. \n + File upload. Now the wiki code editor has a button for inserting a hyperlink to an uploaded file. When the button is clicked, a popup window for upload is shown. Once the user sends the file, the window is closed and a link to the file is inserted in the editor.\n + Embeddable pages. The contents of a wiki page can be embedded in another wiki page by using the syntax `![[Name of Wiki page to be embedded]]`\n + Document preview - allows users viewing how a wiki page markdown text will look like when rendered before saving it. The editor's preview button also allows viewing how a selected markdown code of a wiki page looks like when rendered.\n + Vendored third-party JavaScript dependencies for offline usage. For instance, MWiki has MathJax, pseudocode-JS, and Ace9 in the source code for offline usage even when no CDN is available due to lack of internet connectivity or if the Wiki is used in rescrited environment behind a firewall. \n\n\n#### Access control \n\n + The wiki has the following types of users: *admin*, that can edit the Wiki pages; *guest* a registered used which can view pages even if the wiki is not public, but a guest user cannot edit any page; and *anonymous* users (non logged in users) that can only view pages if the **public** checkbox in the Wiki settings ('/settings' pages) is enabled.\n + Public/private wiki settings - if the **public** checkbox in MWiki settings page is disabled, only logged in users will be able to view the wiki pages and non logged in users will be redirected to the authentiation screen. If this checkbox is enabled, non logged in users can view the wiki. Note that: only users of type administrator can edit the wiki pages and make changes to any content.\n\n\n#### Text Editor Features\n\n+ Markdown **Code editor** built on top of Ace9 JavaScript code editor.\n+ *Clipboard to markdown converter*, which allows turning html content copied from any other web page (aka web site) to MWiki markdown. This feature is similar to Obsidian's non-plain text copying and pasting. \n+ Upload images by pasting them from clipboard. \n     + Usage: Copy any image using the right click on any picture and past it on the text editor sesssion of some wiki page either by using the mouse or typing Ctrl + v.\n+ NOTE: The clipboard features rely on Clibpboard Html5 API, which only is available on [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). Therefore pasting images from clipboard to the wiki text editor only works if the wiki is served on local host or from a domain with https (HTTP + TLS), which may require a reverse proxy such as Caddy or NGinx for TLS/SSL encryption and server authentication.\n+ [VIM](\u003chttps://en.wikipedia.org/wiki/Vim_(text_editor)\u003e) Editor Keybindings: The Wiki editor uses VIM keybindings by default.\n\nSee also:\n\n+ *VIM dot ORG* - Official Website\n  + https://www.vim.org\n+ *Vim (text editor)*\n  + https://en.wikipedia.org/wiki/Vim_(text_editor)\n+ *A Great Vim Cheat Sheet*\n  + https://vimsheet.com/\n+ *Vim Cheat Sheet*\n  + https://vim.rtorr.com\n+ *Vim Key Bindings – Vim Keys List Reference*\n  + https://www.freecodecamp.org/news/vim-key-bindings-reference/\n+ *vi Complete Key Binding List*\n  + https://hea-www.harvard.edu/~fine/Tech/vi.html\n\n\n#### Wiki Markup Language\n\n+ Text formatting:\n   + Italic Text \n   + Bold Text \n   + Strikethrough text (also known as deleted text)\n   + Colored text \n   + Abbreviation, which corresponds to the `\u003cabbr\u003e` html5 tag.\n   + Superscript text \n   + Subscript text \n+ Code blocks with syntax highlight\n+ Tables \n+ List \n   + Bullet List \n   + Ordered Lists \n   + Definition Lists \n+ Scientific and Technical Communication \n   + Built-in inline LaTeX formula (powered by MathJaX)\n   + Built-in LaTeX formula (display mode) with automatic enumeration\n   + Special code blocks for adding custom LaTeX macros\n   + Pseudocode code block \n   + Admonition (also known callout box) for mathematical definition \n   + Admonition for mathematical theorem \n   + Admonition for solved exercise examples \n   + Foldable section for solution of solved exercise \n   + Foldable section for theorem proofs, used in theorem admonition.\n+ Admonitions \n  + Tip Admonition \n  + Note Admonition\n  + Information Admonition\n  + Warning Admonition \n  + Foldable Admonition   \n\nView detailed documentation and examples at: \n\n+ [Markup Language](./README-Markup-Language.md)\n\n## Keyboard Shortcuts (Keybindings)\n\n+ NOTE: It is not necessary to remember those keybindings since there is menu button in the **[Main]** menu, which allows opening the keybind (shortcut) helper window displaying all keybindings.\n+ NOTE: Available since release v0.3\n\n| Shortcut  |     Description                                  |\n| --------- | ------------------------------------------------ |\n| ?         | Toggle keybind (shortcut) helper window.         |\n| ?         | Type ? Question mark again to close this window. |\n| Ctrl /    | Jump to search form.                             |\n| Ctrl e    | Toggle for quick jumpo to Wiki page.             |\n| Ctrl 1    | Go to Index page '/' URL                         |\n| Ctrl 2    | Go to /pages - list of all Wiki pages.           |\n| Ctrl 3    | Go to /tags - list of all tags.                  |\n| Ctrl 5    | Toggle headings of current Wiki page.            |\n| Ctrl 9    | Toggle display all links of current wiki page.   |\n\n## Demonstration \n\n### GIF Animations \n\n**Usage GIF animation**\n\n![](images/mwiki-animation-usage1.gif)\n\n**Copying and pasting images**\n\n![](images/mwiki-animation-usage2.gif)\n\n**Markdown preview feature**\n\n+ The editor button preview allows viewing how a wiki page will look like before saving it. The preview feature also allows viewing how a selected markdown text will look like before saving it.\n\n![](images/wiki-markdown-preview.gif)\n\n\n### Screenshots\n\n**Wiki Screenshot 1**\n\nThis Wiki page, whose relative URL is /wiki/Linear%20Algebra%20New is generated by processing the file 'Linear Algebra New.md'.\n\n![](images/screen1.png)\n\n\n**Wiki Screenshot 2**\n\n![](images/screen2.png)\n\n**Wiki Screenshot 3**\n\n![](images/screen3.png)\n\n**Wiki Screenshot 4**\n\nMWiki code editor powered by Ace9 Javascript code editor.\n\n![](images/screen4.png)\n\n**Wiki Screenshot 5**\n\nMWiki settings page.\n\n![](images/screen5.png)\n\n**Wiki Screenshot 6**\n\nGlobal menu screenshot.\n\n![](images/screen6.png)\n\n**Wiki Screenshot 7**\n\nScreenshot of page menu that allows to perform actions on the current Wiki page.\n\n![](images/screen7.png)\n\n**Wiki Screenshot 8**\n\nIt is possible to fold all Wiki headings for fast navigation on mobile devices or desktop by clicking at the '(F)' button on the top navigation bar.\n\n![](images/screen8.png)\n\n\n**Wiki Screenshot 9**\n\n![](images/screen9.png)\n\n**Wiki Screenshot 10**\n\nThe Wiki has built-in search engine that allows searching for keywords in all Markdown files used for rendering the wiki pages.\n\n![](images/screen10.png)\n\n**Wiki Screenshot 11 - Reference Card**\n\nThis wiki provides a reference card popup windown that provides examples of the MWiki markup language (custom markdown).\n\n(1) Open the reference card.\n\n![](images/refcard1.png)\n\n(2) Reference card with all sections folded.\n\n![](images/refcard2.png)\n\n(3) Reference card with a section unfolded.\n\n![](images/refcard3.png)\n\n\n## Installation \n\n### Installation using UV package manager (1)\n\n[UV](https://github.com/astral-sh/uv) is a newer blazing fast package manager for Python, that can even install multiple specific versions of the Python interpreter without disrupting Python installation used by the system. UV can also install Python tools in isolated environment without breaking the current Python installation. \n\n**STEP 1**\n\nInstall unstable release.\n\n```sh\n$ uv tool install git+https://github.com/caiorss/mwiki\n  ... ... ... ... ... ... ... ... ..\n  Installed 2 executables: mwiki, mwiki-convert\n```\n\nInstall latest stable release: version v0.3.1\n\n```sh\n$ uv tool install https://github.com/caiorss/mwiki/archive/refs/tags/v0.3.1.zip\n```\n\nInstall latest stable release (use hash commit, that cannot be changed after the commit is public): version v0.3.1\n\n```sh\n$ uv tool install https://github.com/caiorss/mwiki/archive/3f4d38a8bc103dee8f89230c6b0a9eefb3083766.zip\n```\n\nInstall release v0.2\n\n```sh\n$ uv tool install https://github.com/caiorss/mwiki/archive/refs/tags/v0.2.zip\n\n##  OR - (Reproducible installation since commits cannot be changed)\n\n$ uv tool install https://github.com/caiorss/mwiki/archive/1a3388679af0a6abaec83f6a88415b617e580c83.zip\n```\n\nInstall release v0.1\n\n```sh\n$ uv tool install https://github.com/caiorss/mwiki/archive/refs/tags/v0.1.zip\n```\n\n**STEP 2** Run executable mwiki:\n\n```sh\n$ mwiki \n\nUsage: mwiki [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  compile  Compile Latex Formulas of .md file or folder to SVG images.\n  convert  Convert from org-mode markup to markdown\n  manage   Manage MWiki settings, including accounts, passwords and etc.\n  server   Run the mwiki server.\n```\n\n**Inspect Executable Files**\n\n```sh\n$ which mwiki\n/home/username/.local/bin/mwiki\n\n$ whereis mwiki\nmwiki: /var/home/username/.local/bin/mwiki\n\n$ file $(which mwiki)\n/home/username/.local/bin/mwiki: symbolic link to /home/username/.local/share/uv/tools/mwiki/bin/mwiki\n\n$ file $(readlink $(which mwiki))\n/home/username/.local/share/uv/tools/mwiki/bin/mwiki: Python script, ASCII text executable\n```\n\n**Uninstall**\n\n### Installation using UV package manager (2)\n\nThis installation procedure uses the UV package manager for installing from the source code instead of github URL.\n\n**STEP 1:** Clone the repository.\n\n```sh\n$  git clone https://github.com/caiorss/mwiki \n```\n\nEnter the source code directory.\n\n```sh\n$ cd mwiki\n```\n\n**STEP 2:** Install MWIKI using UV.\n\n```sh\n$ uv tool install . \n\nResolved 36 packages in 1.07s\nInstalled 36 packages in 119ms\n + blinker==1.9.0\n + cachelib==0.13.0\n + cffi==1.17.1\n + click==8.1.8\n + cryptography==45.0.4\n + flask==3.1.1\n + flask-session==0.8.0\n + flask-sqlalchemy==3.1.1\n + flask-wtf==1.2.2\n + frontmatter==3.0.8\n + greenlet==3.2.3\n + importlib-metadata==8.7.0\n + itsdangerous==2.2.0\n + jinja2==3.1.6\n + linkify-it-py==2.0.3\n + markdown-it-py==3.0.0\n + markupsafe==3.0.2\n + mdit-py-plugins==0.4.2\n + mdurl==0.1.2\n + msgspec==0.19.0\n + mwiki==0.1 \n + pillow==11.2.1\n + pycparser==2.22\n + pygments==2.19.2\n + python-dateutil==2.9.0.post0\n + pyyaml==5.1\n + six==1.17.0\n + sqlalchemy==2.0.41\n + tomli==2.2.1\n + typing-extensions==4.14.0\n + uc-micro-py==1.0.3\n + waitress==3.0.2\n + watchdog==6.0.0\n + werkzeug==3.1.3\n + wtforms==3.2.1\n + zipp==3.23.0\nInstalled 2 executables: mwiki, mwiki-convert\n\n```\n\n**Uninstall**\n\n\n```sh\n$ uv tool uninstall mwiki \nUninstalled 2 executables: mwiki, mwiki-convert\n```\n\n\n### Installation using Pipx pacakge manager \n\n**STEP 1:** Pip and Python are assumed to be already installed.\n\nInstall [pipx](https://github.com/pypa/pipx) tool.\n\n```sh\n$ pip install pipx \n```\n\n**STEP 2:** Install using Pipx\n\nInstall Mwiki using Pipx (MWiki requires Python \u003e= 3.9)\n\n```sh\n$ pipx install git+https://github.com/caiorss/mwiki \n  installed package mwiki 0.1, installed using Python 3.9.19\n  These apps are now globally available\n    - mwiki\n    - mwiki-convert\n    - mwiki_convert\ndone! ✨ 🌟 ✨\n\n```\n\nInstall Mwiki using Pipx and a different version of Python. This command is useful if the default version of Python in the current system is 3.8 or a non supported version.\n\n```\n$ pipx install --python=3.9 git+https://github.com/caiorss/mwiki \n```\n\n### Installation using Docker \n\nDocker is the most realibable way to install Python application since it is reproducible and helps to avoid the Python and Pip dependency hell (also knowns as \"works-on-machine problem\"). \n\n**STEP 1:** Clone the repository\n\n```sh \n$ git clone https://github.com/caiorss/mwiki mwiki\n\n# Enter source code directory\n$ cd mwiki\n```\n\n**STEP 2:** Build the docker image.\n\n```sh\n$ docker build --tag mwiki-server .\n```\n\nor run the Makefile (only supported on Unix-like systems with GNU Make)\n\n```sh\n$ make docker \n```\n\n**STEP 3:** Run MWiki docker image. The $WIKIPATH environment variable is set to any directory containing markdown files, including Obsidian vaults.\n\nCreate a .env file in the current directory containing the initial configuration of MWiki passed as environment variables. (Optional)\n\n\nFile: .env\n\n```\nMWIKI_ADMIN_PASSWORD=u2afb5ck69\nMWIKI_SITENAME=WBook\nWIKI_PUBLIC=\n```\n\nRun docker passing the .env configuration file.\n\n```sh\n$ docker run --rm -it  --privileged \\\n            --network=host --env-file=$PWD/.env \\\n            --volume=\"$WIKIPATH:/wiki\" mwiki-server\n [TRACE] Admin user created OK\n [INFO] Enter the username: admin and password: 'SN81N87JZ6' to log in.\n[2025-01-09 20:00:40 +0000] [1] [INFO] Starting gunicorn 23.0.0\n[2025-01-09 20:00:40 +0000] [1] [INFO] Listening at: http://0.0.0.0:9090 (1)\n[2025-01-09 20:00:40 +0000] [1] [INFO] Using worker: sync\n[2025-01-09 20:00:40 +0000] [7] [INFO] Booting worker with pid: 7\n[2025-01-09 20:00:40 +0000] [8] [INFO] Booting worker with pid: 8\n[2025-01-09 20:00:40 +0000] [9] [INFO] Booting worker with pid: 9\n[2025-01-09 20:00:40 +0000] [10] [INFO] Booting worker with pid: 10\n[2025-01-09 20:00:40 +0000] [11] [INFO] Booting worker with pid: 11\n[2025-01-09 20:00:40 +0000] [12] [INFO] Booting worker with pid: 12\n[2025-01-09 20:00:40 +0000] [13] [INFO] Booting worker with pid: 13\n[2025-01-09 20:00:40 +0000] [14] [INFO] Booting worker with pid: 14\n[2025-01-09 20:00:40 +0000] [15] [INFO] Booting worker with pid: 15\n [TRACE] _username = admin ; _password = SN81N87JZ6\n [WARNING] Note implemented html rendering for foot_note_block =  SyntaxTreeNode(footnote_ref)\n [WARNING] Note implemented html rendering for foot_note_block =  SyntaxTreeNode(footnote_block)\n\n```\n\nRun as a daemon (background service detached from terminal):\n\n```sh\n$ docker run --detach \\\n           --name=mwiki  \\\n           --network=host \\\n           --env-file=$PWD/.env \\\n           --privileged \\\n           --volume=\"$PWD/pages:/wiki\" mwiki-server\na6f0838f5159ff75aa25228fafdbd2f4fe1432c3359a9dc5d3ec84b10d801577\n \n```\n\nView logs from mwiki container:\n\n```sh\n$ docker logs -f mwiki\n[2025-01-09 20:06:23 +0000] [1] [INFO] Starting gunicorn 23.0.0\n[2025-01-09 20:06:23 +0000] [1] [INFO] Listening at: http://0.0.0.0:9090 (1)\n[2025-01-09 20:06:23 +0000] [1] [INFO] Using worker: sync\n[2025-01-09 20:06:23 +0000] [7] [INFO] Booting worker with pid: 7\n[2025-01-09 20:06:23 +0000] [8] [INFO] Booting worker with pid: 8\n[2025-01-09 20:06:23 +0000] [9] [INFO] Booting worker with pid: 9\n[2025-01-09 20:06:23 +0000] [10] [INFO] Booting worker with pid: 10\n[2025-01-09 20:06:23 +0000] [11] [INFO] Booting worker with pid: 11\n[2025-01-09 20:06:23 +0000] [12] [INFO] Booting worker with pid: 12\n[2025-01-09 20:06:23 +0000] [13] [INFO] Booting worker with pid: 13\n[2025-01-09 20:06:23 +0000] [14] [INFO] Booting worker with pid: 14\n[2025-01-09 20:06:24 +0000] [15] [INFO] Booting worker with pid: 15\n\n```\n\nStop MWiki container:\n\n```\n$ docker stop mwiki \nmwiki\n```\n\nStart MWiki container \n\n```sh\n$ docker start mwiki \n```\n\nRestart MWiki container software.\n\n```sh\n$ docker restart mwiki\n```\n\nChange site name using the built-in CLI (Command Line Interface)\n\n\n```sh\n$ docker exec -it mwiki python -m mwiki  manage --sitename=WNotes\n [*] Site name changed to: WNotes\n```\n\nChange admin password.\n\n```sh\n$ docker exec -it mwiki python -m mwiki  manage --admin-password=somePassNewPassword\n```\n\n**STEP 5:** \n\nOpen MWiki in the web browser, in the port 8080 by copying and pasting the URL http://localhost:8000 and enter 'admin' in the username entry and the initial admin password in the password field. The initial admin password is provided in the previous command output. In this password is '0JAJ6UAMUA', which is a random generated string unique per MWiki installation.\n\n**STEP 6:**\n\nOpen the settings page http://localhost:8000/admin and change the Wiki settings. Then go the URL http://localhost:8000/user and change the admin password. Note that user passwords are never stored in plaintext, they are always stored in hashed form for security reasons.\n\n\n### Installation via Docker-Compose or Podman-Compose \n\n\n**STEP 1:** Clone the repository\n\n```sh \n$ git clone https://github.com/caiorss/mwiki mwiki\n\n# Enter source code directory\n$ cd mwiki\n```\n\nIf the repository is already cloned, it is possible to get the latest changes by running\n\n```\n$ git pull\n```\n\n**STEP 2:** Switch to a stable release\n\n```sh\n$ git checkout \u003c\u003cRELASE-VERSION\u003e\u003e\n\n# For instance\n\n$ git checkout v0.31\n```\n\n**STEP 3:** Edit the config.env file.\n\nFile: config.env\n\n```sh\n# MWiki configuration files \n#----------------------------------#\n\nMWIKI_SERVER_ADDR=mwiki \nMWIKI_SERVER_PORT=9090\n\n# Path to wiki folder, where *.md markdown files, images and other \n# files will be stored.\nMWIKI_PATH=./sample-wiki\n\n# Password of main admin\nMWIKI_ADMIN_PASSWORD=mypasswd\n\n# Name of the Wiki (Name of the website)\nMWIKI_SITENAME=MyNoteBook\n\n# URL which the website is hosted or just domain name \nMWIKI_WEBSITE=localhost sbox.ts \n\n# Configure MWiki as a private Wiki. \n# =\u003e Only logged in users can view wiki pages. \n# MWIKI_PUBLIC=   \n\n# Configure MWiki  as a public Wiki.\n# =\u003e Anonymous users can view wiki pages, however only \n# admin users can edit.\nMWIKI_PUBLIC=true\n\n# Server static files using Caddy or NGinx \nMWIKI_X_ACCEL_REDIRECT=true\n\n#----------------------------------------------------##\n##      Less common Settings for certificate         ##\n#----------------------------------------------------##\n# They are not needed if the server is hosted in a machine\n# with static and public IP address. Those settings are only\n# required when hosting in internal networks (LANs).\n#\nMWIKI_INTERNAL_CA=\nMWIKI_ACME_CA_URL=\n```\n\n\n**STEP 4:** Run docker-compose or podman compose for the deployment.\n\nDeploy with docker-compose.\n\n```sh\n$ docker-compose --env-file=./config.env up -d \n```\n\nDeploy with podman-compose.\n\n```sh\n$ podman-compose --env-file=./config.env up -d \n```\n\n**STEP 5:** TLS/SSL Certificates\n\nIf the MWiki is hosted in a machine with static and public IP address reacheable from anywhere on the internet and MWiki domain points to this IP address, Caddy will automatically obtain the TLS/SSL certificate from Let's Encrypt CA - Certificate authority. \n\nIf this application is hosted on local network or site-to-site VPN, such as tailscale and using Let's Encrypt CA is not possible, Caddy can be turned into a local CA - Certificate Authority by editing the config.env and changing \n\n```\nMWIKI_INTERNAL_CA=true\n```\n\nThis step creates an endpoint \n\n+ `https://\u003cmwiki-website-domain\u003e/root.crt`\n\nwhere the user can download the root CA certificate and install it on web browsers or phones. This root CA cerfiticate can be downloaded using curl. This procedure is useful for self-hosting MWiki on home labs.\n\n```sh\n$ curl -O -k --silent https://\u003cmwiki-website-domain\u003e/root.crt\n```\n\nSee also:\n\n+ *Set up Certificate Authorities (CAs) in Firefox*\n  + https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox\n+ *Installing a Root Certificate Authority in Firefox* \n  + https://chewett.co.uk/blog/854/installing-root-certificate-authority-firefox/\n+ *How to Add a Certificate on Android? Step by Step*\n  + https://www.airdroid.com/mdm/add-certificate-android/\n\n\n## Post-Installation - Access MWiki in the local network\n\n**STEP 1:** \n\nGet the hostname of the computer where mDNS is installed on Linux, MacOSX or Windows by running the following command in a terminal emulator. In Microsft Windows, a terminal emulator can be opened by typing Windows-Key + R and entering 'cmd'.\n\n```sh\n$ hostname \n```\n\nand also get the computer IP address on Microsoft Windows for debugging purposes.\n\n```sh\n$ ipconfig\n```\n\non Linux the IP address of the server in the local network can be obtained by running.\n\n```sh\n# Older versions of Linux distributions, BSD and MacOSX\n$ ifconfig\n\n## Newer version of Linux distributions\n$ ip addr\n```\n\n**STEP 2:** \n\nIf the MWiki server is installed and running and it is possible to access the server from any computer in the local network with mDSN - Multicast DNS enabled by opening the one the of the following URLs in any web browser from any device or computer in the local network, including smart phones or tablets. \n\n+ http://dummy.local:8080 if MWiki is listening to TCP port 8080\n+ http://dummy.local  if MWiki is listening to port 80 (default HTTP TCP port)\n+ http://192.168.0.106:8080 if the server IP address obtained in the step 1 is 192.168.0.106 and MWiki is listening to port 8080\n+ http://192.168.0.106 if the server IP address obtained in the step 1 is 192.168.0.106 and MWiki is listening to port 80.\n\nObservations:\n\n1. Note that *dummy* is the hostname (network name) of the computer running MWiki obtained in the step 1 with the command `$ hostname`.\n2. In most corporate network, the multicast network traffic is disabled by default, while in most home networks the multicast network traffic, including multicast DNS is enabled by default. \n\nMWiki can be started with the command\n\n```\n$ mwiki server  --wsgi --port=9010 --wikipath=/home/user/path/to/wiki/repository\n```\n\nIt is recommend to run the application using Caddy or NGinx reverse proxy servers as they provide TLS encryption and better performance for serving static files and handling higher network traffic.\n\n**STEP 3:**\n\nIn order to be able to access MWiki or any other web server from other computers or devices, it may be necessary to open TCP ports in the operating system firewall.\n\nOpen port 8080 in Microsoft Windows (requires opening a terminal with administrator privilegees).\n\n```sh\n$ netsh firewall add portopening TCP 8080 \"MWIki server port\"\n```\n\nOpen port 8080 in Linux with Iptables (Default Linux firewall, all other Linux firewalls are wrappers around Iptables).\n\n```sh\n$ sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT\n```\n\nOpen port 8080 in Linux with UFW (Uncomplicated Firewall), mostly used by Debian and Ubuntu derived Linux distributions.\n\n```sh\n$ sudo ufw allow 8080/tcp\n```\n\nOpen port 8080 in Linux with firewalld.\n\n```sh\n$ sudo firewall-cmd --add-port=8080/tcp --permanent\n$ sudo firewall-cmd --reload\n```\n\n**Further Reading**\n\n+ *Open TCP Port 80 in Windows Firewall Using Netsh* \n  + https://www.wiki.mcneel.com/zoo/homenetsh\n+ *Linux Open Port 80 (HTTP Web Server Port)*, Vivek Gite (2022), Cyberciti\n  + https://www.cyberciti.biz/faq/linux-iptables-firewall-open-port-80/\n+ *5 ways to open a port in Linux explained with examples*, Arun Kumar (2023), FOSS Linux\n  + https://www.fosslinux.com/111811/5-ways-to-open-a-port-in-linux-explained-with-examples.htm\n+ *Linux .local domain*\n  + https://en.wikipedia.org/wiki/.local\n+ *Linux Open Port: Step-by-Step Guide to Managing Firewall Ports*, Vijaykrishna Ram and Anish Singh Walia, Digital Ocean\n  + https://www.digitalocean.com/community/tutorials/opening-a-port-on-linux\n+ *Using mDNS aliases within your home network*, Andrew Dupont (2022)\n  + https://andrewdupont.net/2022/01/27/using-mdns-aliases-within-your-home-network/\n+ *How to set up mDNS on an ESP32*\n  + https://lastminuteengineers.com/esp32-mdns-tutorial/\n+ *mDNS, hostname.local, and WSL2*, Nelsons' log\n  + https://nelsonslog.wordpress.com/2022/01/06/mdns-hostname-local-and-wsl2/\n+ *Multicast DNS (MDNS) on Home Networks*\n  + https://stevessmarthomeguide.com/multicast-dns/\n+ *Pros and Cons of Using Multicast DNS*, Networking Interview\n  + https://networkinterview.com/pros-and-cons-of-using-multicast-dns/\n+ *Android silently picks up long-awaited mDNS feature*, Anroid Police\n  + https://www.androidpolice.com/android-mdns-local-hostname/\n+ *Use network service discovery*, Android Developers\n  + https://developer.android.com/develop/connectivity/wifi/use-nsd\n+ *Multicast Application Protocol mDNS for Local Discovery*, Expressif (ESP32) Docs\n  + https://espressif.github.io/esp32-c3-book-en/chapter_8/8.2/8.2.4.html#multicast-application-protocol-mdns-for-local-discovery\n\n\n## Development \n\n**STEP 1:** Clone the repository\n\n```sh\n$ git clone \u003cREPOSITORY-URL\u003e  mwiki\n$ cd mwiki\n```\n\n**STEP 2:** Install [Poetry](https://python-poetry.org/) package manager if it is not installed yet.\n\n```sh\n$ pip install poetry \n```\n\n**STEP 2:** Install dependencies with Poetry.\n\n```sh\n$ poetry install \n```\n\n**STEP 3:** Generate VScode JSON files .vscode/settings.json and .vscode/launch.json for integrating Poetry, Virtualenv and VSCode editor.\n\n```\n$ make vscode\n```\n\nor run\n\n```sh\n$ pythopn vscode.py\n\n## OR \n\n$ ./vscode.py # On Unix-like operating system (Linux, BSD or MacOSX)\n```\n\n**STEP 4:** Run MWiki in development mode.\n\n```sh\n $ poetry run mwiki  server  --debug \\\n                              --host=0.0.0.0 \\\n                              --port=8000  \\\n                              --wikipath=/path/to/wiki-markdon-files/directory/notes\n [TRACE] Admin user created OK\n [INFO] Enter the username: admin and password: '0JAJ6UAMUA' to log in.\n * Serving Flask app 'mwiki.server'\n * Debug mode: on\nWARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.\n * Running on all addresses (0.0.0.0)\n * Running on http://127.0.0.1:8000\n * Running on http://192.168.0.103:8000\nPress CTRL+C to quit\n * Restarting with stat\n [INFO] Enter the username: admin and password: '0JAJ6UAMUA' to log in.\n * Debugger is active!\n * Debugger PIN: 795-641-657\n```\n\nThe notes folder, in this case '/path/to/wiki-markdon-files/directory/notes', is just a folder containing markdown files and images. This folder can also be a *Obisdian Vault*, a repository of markdown files and images.\n\n```sh\n $ ls notes/\n'Android OS for Mobile Devices.md'\n'APL - Programming Languages.md'\n articles/\n'Authoring Tools.md'\n AWS_Cloud.md\n aws.org\n'Backend Design and Scalability.md'\n'Backup and Digital Preservation.md'\n Bookmarks.md\n books/\n'Books and Files.md'\n'Business News.md'\n'Caching Algorithms and Synchronization.md'\n'Collected Info.md'\n'Command Line.md'\n'Compiler Design.md'\n'Computer Architecture.md'\n   ... ... ...  ... ... ... ... ...\n   ... ... ...  ... ... ... ... ...\n\n```\n\nEvery markdown file is rendered as wiki page. For instance the file 'Business News.md' corresponds to the wiki page \n\n+ `http://\u003cPAGE-DOMAIN\u003e/wiki/Business%20News`\n\nor\n\n+ `http://localhost/wiki/Business%20News`\n\n\n**STEP 5:** \n\nOpen MWiki in the web browser, in the port 8080 by copying and pasting the URL http://localhost:8000 and enter 'admin' in the username entry and the initial admin password in the password field. The initial admin password is provided in the previous command output. In this password is '0JAJ6UAMUA', which is a random generated string unique per MWiki installation.\n\n**STEP 6:**\n\nOpen the settings page http://localhost:8000/admin and change the Wiki settings. Then go the URL http://localhost:8000/user and change the admin password. Note that user passwords are never stored in plaintext, they are always stored in hashed form for security reasons.\n\n\n\n## Companion Software and Tools\n\nThe following set of companion sotfware or apps are recommended for MWiki as they can provide additional features and improve usage.\n\n\n**Searche Engine**\n\n+ https://noai.duckduckgo.com \n  + Search engine without false and misleading AI summary.\n\n\n**Online Tools**\n\n+ *QuickLatex*\n  + https://www.quicklatex.com\n  +  This online tool allows quickly viewing and rendering LaTeX math expressions without needing to install anything. \n+ *Table Generator for Markdown, LaTeX and MediaWiki*\n  + https://www.tablesgenerator.com\n+ *Detexify*\n  + https://detexify.kirelabs.org/classify.html\n  + *Allows to recognize LaTeX symbols by drawing them by hand.*\n+ *LaTeX Equation Editor*  \n  + https://editor.codecogs.com/\n+ *Mathcha.io*\n  + https://www.mathcha.io\n  + *Online tool for scientific/technical illustration drawing, which supports LaTeX symbols and has many building blocks for drawing geometric, electrical, mechanical and computer science diagrams or schemas. \n+ *How to write algorithm in Latex*\n  + https://shantoroy.com/latex/how-to-write-algorithm-in-latex\n+ *LaTeX/Algorithms - Wikibooks*\n  + https://en.wikibooks.org/wiki/LaTeX/Algorithms\n\n\n**Browser Addons**\n\n+ *LibreWolf* - Fork of Firefox Web Browser\n  + https://librewolf.net/\n  + *Modified Firefox web browser hardened for better security, privacy and protection against tracking.*\n+ *Obsidian Web Clipper* (Firefox Addon)* \\[BEST\\]\n  + https://addons.mozilla.org/en-US/firefox/addon/web-clipper-obsidian\n  + Extension that lets users to save web pages in markdown format or turn selected parts of the web page into markdown. This tool can be used with MWiki for extracting information from web pages as MWiki markup language is compatible with Obsidian markdown. \n+ *Web Archives* - Search for older versions of current URL win Web Archiver, archive.is and other sites.\n  + https://addons.mozilla.org/en-US/firefox/addon/view-page-archive/\n  + *View archived and cached versions of web pages on various search engines, such as the Wayback Machine and Archive․is.*\n+ *Allow Right Click - Re-enable right-click on websites that overwrite it* (Firefox)\n  + https://addons.mozilla.org/en-US/firefox/addon/re-enable-right-click/\n  + *The \"Allow Right-Click\" extension modifies some JavaScript methods to enable the original right-click context menu when a web page intentionally blocks right-clicking on its content. Most modern browsers permit JavaScript to disable the default context menu when a web page provides its custom context menu for its content (such as in Google Docs). However, this ability can also allow website owners to disable the right-click context menu without providing any useful functionality. The extension adds a button to the toolbar area of the user's browser. Clicking the extension's icon injects a small script into the current page to remove the context menu blockage. It is important to note that the extension does not inject any code by default on any web page; it only does so on user action. Users can click the extension button to release the restriction when a website blocks the right-click context menu without offering a custom context menu.*\n+ *Script Blocker Ultimate* - (NoScript, Disable JS)\n  + https://addons.mozilla.org/en-US/firefox/addon/script-blocker-ultimate/\n  + *Extension for toggling execution of Javascript, which allows disabling and enabling JavaScript.*\n+ *NoScript* \n    + https://noscript.net/\n    + *Browser extension that blocks scripts by default.*\n+ *Tree Style Tabs for Firefox*\n  + https://addons.mozilla.org/en-US/firefox/addon/tree-style-tab\n\n\n\n**Translation and Text-to-speak**\n\n+ *Speech Note - Flathub* \\[Linux Flatpak APP\\] (Offline \"G00gl3 Translator\")\n  + https://flathub.org/apps/net.mkiol.SpeechNote\n  + Brief: *Speech Note let you take, read and translate notes in multiple languages. It uses Speech to Text, Text to Speech and Machine Translation to do so. Text and voice processing take place entirely offline, locally on your computer, without using a network connection. Your privacy is always respected. No data is sent to the Internet.*\n  + WARNING: Automated text translation tools are based on word probability in the same way as the hyped LLM - Large Laguage Models. As a result, they may not be able to accurately translate slangs, jargons, popular sayings and language nuances. Moreover, they are more likely to fail for languages distant from European languages and English. It is also worth noting that some language varieties or dialects, such as the Bavarian German dialect, might exist mostly in spoken form and unfortunately, not exist in significant amount in written form, what makes it harder to automated tools to translate the information.\n\n\n**Screenshot Tools**\n\nNote: These tools allows taking screenshots of select part of the screen and pasting the screenshot image at the target application or MWiki editor by typing Ctrl + v.\n\n\n- *Spetacle* \\[BEST\\]\n   + https://apps.kde.org/spectacle/\n   + *KDE Plasma tool for taking screenshots. It also allows selecting rectangular are of the screen and adding texts and annotations. This app is available in any Linux distribution with KDE plasma desktop environment.*\n- *Flameshot*\n   + https://flameshot.org\n   + *Cross platform screenshot tool available for Microsoft Windows, Linux distributions and Apple's MacOSX.*\n- *Flameshot - Flatpak*  \n   + https://flathub.org/apps/org.flameshot.Flameshot\n- *KSnip - Flathub*  (KDE/QT Flatpak App)\n   + https://flathub.org/apps/org.ksnip.ksnip\n   + *Ksnip is a Qt based cross-platform screenshot tool that provides many annotation features for your screenshots.*\n- *Shutter Screenshot tool* \\[BEST\\]\n   + https://shutter-project.org\n   + =\u003e Note: Note available as AppImage or flatpak app. It is easier to install Shutter in Debian-based or Ubuntu-based Linux distributions.\n\n\n**Video Recorder**\n\n+ *Peek - Flathub* (Screen Recorder - can create GIF animation or WebM and MP4 videos)\n  + https://flathub.org/apps/com.uploadedlobster.peek\n  + Brief: * Peek makes it easy to create short screencasts of a screen area. It was built for the specific use case of recording screen areas, e.g. for easily showing UI features of your own apps or for showing a bug in bug reports. With Peek you simply place the Peek window over the area you want to record and press \"Record\". Peek is optimized for generating animated GIFs, but you can also directly record to WebM or MP4 if you prefer.*\n\n**Container Orchestration Tools**\n\n+ *Docker Compose*, Docker Company Official Docs\n  + https://docs.docker.com/compose/\n+ *Podman Compose*, Red Hat \n  + https://docs.podman.io/en/latest/markdown/podman-compose.1.html\n\n\n**Site-To-Site Mesh VPN (Virtual Private Network)**\n\nA site-to-site mesh VPN such as **tailscale** can be helpful for self hosting this application in a private local network and accessing it from anywhere around the world without exposing any TCP or UDP ports to the internet.\n\n+ *Tailscale* - Official Website\n  + https://tailscale.com\n  + Note: Only some tailscale clients are open source, the default tailscale server provided as SAAS (Software-As-Service) is not open source, although there exists the **Headscale** open source implementation of tailscale server.\n+ *Tailscale Client Download*\n  + https://tailscale.com/download\n+ *Tailscale Client for Android on F-Droid App Store* (App Store for Open Source Android apps compiled with reproducible build)\n  + https://f-droid.org/packages/com.tailscale.ipn\n+ *Headscale Server* (Open source, suitable for homelabs and self-hosting)\n  + https://headscale.net/stable\n+ *Headscale Server - Github Repository* (Written in GO - Golang)\n  + https://github.com/juanfont/headscale\n\n\n##  Further Reading \n\n+ *If it is worth keeping, save it in Markdown*\n  + https://p.migdal.pl/blog/2025/02/markdown-saves\n+ *Exposing a web service with Cloudflare Tunnel*, Erissa A (2022)\n  + https://erisa.dev/exposing-a-web-service-with-cloudflare-tunnel/\n  + *What if you could host a web service with no ports exposed? With Cloudflare Tunnel, you can!*\n  + COMMENT: For people who does not trust Cloudflare, a self-hosted Tailscale mesh VPN is a better choice. Tailscale allows establishing a direct end-to-end encrypted tunnel between tailscale client nodes (machines with tailscale client installed). As a result, any node in a taiscale network can access any web service exposed by other tailscale nodes. For instance, if an Android or Iphone has a taiscale client app installed. It is possible to browse a websiste hostead in the local network, possibly behding a NAT - Network Address Translator which blocks incoming connections by default, by opeing the URL http://dummy:8080 or http://dummy.net.ts:8080, where dummy is the hostname or tailscale name of the computer that hosts the web server. Tailscale is not only useful for accessing local web servers from anywhere without exposing any TCP or UDP port to the internet, it is also helpful for accessing windows shared forlders (SAMBA/SMB), sometimes called Windows shares, and Windows Machines remotely through VNC or remote desktop. \n  + COMMENT: Exposing a local web server to the internet with Taiscale requires installing a tailscale client in the local computer hosting the web server and a tailscale client in the VPS - Virtual Private Server, a virtual machine, hosted on the cloud with public IP address. All it is need is to add a configuration to caddy or nging in the remote machine to forward the network traffic of ports 80 (http) and 443 (https) to the tailscale IP addres or hostname of the local computer, for instance dummy.net.ts is the hostanme or tailscale name of the local computer is dummy. The role of a tailscale server, that must be installed in machine with static and public IP address, is only coordinating connections between clients. Once a connection from client-to-client has been established, the network traffic between clients does not goes thorugh the server. \n+ *Scientific Articles*, MyST \n  + https://mystmd.org/guide/quickstart-myst-documents\n+ *R Markdown* \n  + https://rmarkdown.rstudio.com/\n  + *R Markdown documents are fully reproducible. Use a productive notebook interface to weave together narrative text and code to produce elegantly formatted output. Use multiple languages including R, Python, and SQL.*\n+ *MyST syntax cheat sheet*, Jupyter Book\n  + https://jupyterbook.org/en/stable/reference/cheatsheet.html\n  + NOTE: MWiki syntax is mostly compatible with MyST syntax because it uses the same markdown parser developed by Jupyter Book project. Credits should be given to MyST markdown project.\n+ *Working with MyST Markdown*, MyST \n  + https://mystmd.org/guide/quickstart-myst-markdown\n+ *Export Static Documents*, MyST \n  + https://mystmd.org/guide/quickstart-static-exports\n+ *Try MyST*, MyST \n  + https://mystmd.org/sandbox\n+ *CommonMark*, MyST \n  + https://mystmd.org/guide/commonmark\n+ *CommonMark Spec*, CommonMark\n  + https://spec.commonmark.org/0.31.2/#introduction\n+ *reStructuredText* (Python RST syntax)\n  + https://docutils.sourceforge.io/rst.html\n+ *Documentation Audiences*, OpenEdx\n  + \u003chttps://docs.openedx.org/en/latest/documentors/concepts/about_doc_audiences.html\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiorss%2Fmwiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiorss%2Fmwiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiorss%2Fmwiki/lists"}