HTML-PY-Editor – Setting Up Step by Step
========================================

The HTML-PY-Editor is the FreeHTML-Editor with an additional tab “Upload”: with it, your finished website
goes straight to your web server. To make this possible, a small program written in the Python programming
language runs alongside it on your computer. This guide is written for people without any IT knowledge.

How this guide is structured:
  - Every step has a number and contains exactly one action.
  - What is in “quotation marks” appears exactly like that on the screen (buttons, menus, messages).
    Messages in the black window or Terminal are quoted in English; on a computer set to German,
    they appear in German.
  - Commands are indented and on a line of their own. You copy them unchanged.
  - Under “If it looks different” you will find what to do if your screen shows something else.

Free software (GPL-3.0-or-later), without warranty. © 2026 Peter Hoenig, MY COACHING FOR YOU.
German version of this guide: LIESMICH.txt in the same folder.


Contents
--------
   1. Which way suits me?
   2. What you need
   3. Briefly explained: the Terminal (Mac and Linux only)
   Part A – Windows 10 and 11
   Part B – Mac (including older Macs with an Intel processor, e.g. MacBook Pro 2019)
   Part C – Linux
   4. How to check that it worked
   5. First steps in the editor
   6. Common problems and solutions
   7. Removing (uninstalling)
   8. Good to know


1. Which way suits me?
----------------------
   - Do you want to design your website and upload the finished files yourself (e.g. with FileZilla),
     or leave that to someone else?
     → Use the FreeHTML-Editor. It is a single file (“freehtml-editor.html”). You open it in Google Chrome
       or Microsoft Edge and install nothing. You do not need this guide then.

   - Do you want to upload the website to your web server directly from the editor?
     → Use the HTML-PY-Editor (this package). The set-up takes about 20 to 30 minutes the first time.
       After that you start the editor in a few seconds.

   Both editors open the same website projects. You can switch at any time.


2. What you need
----------------
   a) A computer with one of these systems:
      - Windows 10 or Windows 11
      - Mac with macOS 13 “Ventura” or newer. This applies to Macs with an Intel processor just as much as to
        Macs with an Apple chip (M1, M2 …).
        With macOS 10.15 “Catalina”, 11 “Big Sur” or 12 “Monterey” the editor usually still runs.
        However, since summer 2026 Google Chrome and Microsoft Edge no longer receive security updates there.
        If your Mac is older than macOS 10.15, unfortunately it will not work.
      - Linux with a graphical desktop (e.g. Ubuntu, Linux Mint, Debian, Fedora)

      How to find out which system you have:
      - Windows: Press the Windows key, type   winver   and press the Enter key.
        A small window “About Windows” names “Windows 10” or “Windows 11”.
      - Mac: Click the Apple symbol (the apple) at the top left and then “About This Mac”. The window shows
        the name (e.g. “macOS Sequoia”) and the “Version” (e.g. 15.7). The line “Processor” with “Intel”
        indicates an Intel Mac; if it says “Chip” with “Apple M…”, it is a Mac with an Apple chip.
        For orientation: 10.15 = Catalina, 11 = Big Sur, 12 = Monterey, 13 = Ventura, 14 = Sonoma,
        15 = Sequoia, 26 = Tahoe.
        A 2019 MacBook Pro can be updated up to macOS 15 Sequoia (the 16-inch model even up to
        macOS 26 Tahoe). You will find the update under “System Settings” › “General” › “Software Update”
        (on older versions: “System Preferences” › “Software Update”).

   b) A suitable browser: Google Chrome or Microsoft Edge (Chromium or Brave also work).
      Safari and Firefox cannot edit folders on your computer and are therefore not suitable.
      On Windows 10 and 11, Microsoft Edge is already installed.

   c) The password of your user account. On a Mac, the Python installer asks for it; on Linux, the
      “sudo” command does. On Windows you usually do not need one.

   d) An internet connection, but only for the set-up (about 100 MB is downloaded) and later for
      uploading.

   e) For uploading (not for the set-up): the access details from your hosting provider. These are the
      server (also called “host”), the user name, the password, the port and the directory of your website.
      You will find them in your hosting provider's customer area, usually under “SFTP access”,
      “SSH access” or “FTP access”.


3. Briefly explained: the Terminal (Mac and Linux only)
-------------------------------------------------------
   The Terminal is a window in which you type commands. You do not have to understand any of it; you only
   copy the commands from this guide.

   Opening the Terminal:
   - Mac: Press the keys cmd (⌘) and Space at the same time. A search field (“Spotlight”) appears.
     Type   Terminal   and press the Return key (↩).
     Or in the Finder: “Applications” › “Utilities” › “Terminal”.
   - Linux (Ubuntu, Mint): Press Ctrl + Alt + T. Or search for “Terminal” in the start menu.

   You now see a window whose last line ends in  %  or  $  – the cursor blinks after it.

   Entering a command:
   1. Select the command in this guide with the mouse (only the line, without the spaces in front of it).
   2. Copy it: Mac cmd + C, Linux Ctrl + C.
   3. Click in the Terminal window.
   4. Paste it: Mac cmd + V, Linux Ctrl + Shift + V.
   5. Press the Return key (on Linux: the Enter key).
   6. Wait until a line ending in  %  or  $  appears again. Then the command has finished.
      Many commands show nothing when everything has worked. That is fine.

   If a command asks for your password (“Password:” or “[sudo] password for …”), type it in.
   No characters appear while you do so, not even dots. That is normal. Then press the Return key.

   Cancelling a running command: Press the keys control (Mac) or Ctrl (Linux) and C at the same time.
   Tip: With the ↑ arrow key you bring back the command you entered last.


Part A – Windows 10 and 11
==========================

A1. Install Python (once only, about 5 minutes)
   If you have already installed Python (version 3.8 or newer), you can carry on with A2.

   1. In your browser, open the page   https://www.python.org/downloads/
   2. Below the large yellow button, click the link “standalone installer for Python 3.…”
      (the numbers change over time).
      The browser now downloads a file such as “python-3.15.0-amd64.exe” into the “Downloads” folder.
      (The yellow button itself downloads the “Python install manager”. That works too, but it is operated
      differently from what is described here.)
   3. Open the downloaded file: click the file name in the browser or double-click it in the “Downloads”
      folder in File Explorer.
   4. You see the window “Install Python 3.… (64-bit)”. At the very bottom, tick the box
      “Add python.exe to PATH”. This step is important.
   5. Click “Install Now”.
      If Windows asks “Do you want to allow this app to make changes to your device?”, click “Yes”.
   6. Wait until “Setup was successful” appears (1 to 3 minutes).
   7. Click “Close”.

   If it looks different:
   - The window only offers “Modify”, “Repair” and “Uninstall”: Python is already installed.
     Click “Cancel” and carry on with A2.

A2. Download and unpack the package (about 2 minutes)
   1. Download the file “html-py-editor.zip”. Afterwards it is in the “Downloads” folder.
   2. Open File Explorer (folder icon in the taskbar) and click “Downloads” on the left.
   3. Right-click “html-py-editor.zip” and then click “Properties”.
   4. If there is an “Unblock” tick box next to “Security” at the bottom, tick it. Click “OK”.
      (If the box is missing, just click “OK”.) Windows then will not ask about every file later.
   5. Right-click “html-py-editor.zip” and then click “Extract All…”.
   6. Leave the suggested folder as it is and click “Extract”.
      You now see a folder “html-py-editor”. Open it by double-clicking and, if there is another folder
      “html-py-editor” inside it, open that one as well. You then see files such as
      “HTML-PY-Editor starten (Windows)” (= start the editor) and “Module installieren (Windows)”
      (= install modules).
      (Windows usually does not show the extension “.bat”. In the “Type” column it says “Windows Batch File”.)

   Tip: Afterwards you can move the folder to a better place, e.g. to “Documents”.

A3. Install modules (once only, 1 to 3 minutes)
   1. Double-click “Module installieren (Windows)”.
   2. A black window opens. It shows “Step 1 of 3” to “Step 3 of 3” one after the other and, in between,
      many lines. Wait.
   3. When “Done - the modules are installed.” appears, press any key. The window closes.

   If it looks different:
   - “Windows protected your PC”: Click “More info” and then “Run anyway” (provided you downloaded the
     package from the publisher's website).
   - “Python was not found on this computer”: Repeat A1 and make sure to tick the box
     “Add python.exe to PATH”. Then A3 again.
   - “The installation did not work”: Check your internet connection and repeat A3.
   - “The modules were downloaded but cannot be loaded”: The folder is nested too deeply. Move the folder
     “html-py-editor”, e.g. to “Documents”, and repeat A3 there.

A4. Start the editor (every time)
   1. Double-click “HTML-PY-Editor starten (Windows)”.
   2. A black window “HTML-PY-Editor” opens and, shortly afterwards, the editor in Edge or Chrome.
   3. Leave the black window open while you work. You can minimise it.
   4. To quit, close the black window (cross at the top right).

   Tip for a quick start: Right-click “HTML-PY-Editor starten (Windows)” › (on Windows 11 first
   “Show more options”) › “Send to” › “Desktop (create shortcut)”. After that you start the editor by
   double-clicking the shortcut on the desktop.

   Continue with section 4 (“How to check that it worked”).


Part B – Mac (including older Macs with an Intel processor)
===========================================================
   This route needs no Homebrew and no developer tools. It is the same for Macs with an Intel processor
   (e.g. MacBook Pro 2019) and for Macs with an Apple chip. Section 2 tells you which system you have.

B1. Install Google Chrome (if not already installed, about 3 minutes)
   If you already have Chrome or Microsoft Edge, carry on with B2.

   1. In Safari, open the page   https://www.google.com/chrome/
   2. Click “Download Chrome”. The file “googlechrome.dmg” lands in the “Downloads” folder.
   3. In the Finder, open the “Downloads” folder and double-click “googlechrome.dmg”.
   4. In the new window, drag the Chrome icon onto the “Applications” folder.
   5. Open Chrome once: Finder › “Applications” › double-click “Google Chrome”. If macOS asks whether you
      want to open the program downloaded from the internet, click “Open”.

B2. Install Python (once only, about 5 minutes)
   1. In your browser, open the page   https://www.python.org/downloads/
   2. Click the yellow button “Download Python 3.…” (the numbers change over time).
      A file such as “python-3.15.0-macos11.pkg” lands in the “Downloads” folder. The “macos11” in the name
      is only a label; the installer runs from macOS 10.15 onwards and also on Intel Macs.
   3. In the Finder, open the “Downloads” folder and double-click this file.
   4. The installer opens. At “Introduction” and “Read Me”, click “Continue” each time.
   5. At “License”: click “Continue” and then “Agree”.
   6. Click “Install”.
   7. Enter the password of your Mac user account and click “Install Software”.
   8. When “The installation was successful.” appears, click “Close”. You can answer the question of whether
      the installer should be moved to the Trash with “Move to Trash”.
   9. A Finder window “Python 3.…” has opened. In it, double-click
      “Install Certificates.command”. A Terminal window runs briefly and ends with
      “update complete”. Close this window.
      (If no Finder window has opened: Finder › “Applications” › folder “Python 3.…”.)

   If it looks different:
   - A window offers to install the “command line developer tools”: Click “Cancel”. You do not need them;
     Python from python.org is enough.

B3. Download and unpack the package (about 3 minutes)
   1. Download the file “html-py-editor.zip”. It lands in the “Downloads” folder.
   2. Open the Terminal (see section 3).
   3. Enter this command (it unpacks the file into the new folder “html-py-editor-paket” in your home
      folder):

         ditto -x -k ~/Downloads/html-py-editor.zip ~/html-py-editor-paket

      If macOS asks whether “Terminal” may access the “Downloads” folder, click “OK” or
      “Allow”.
   4. Enter this command (it removes the lock that macOS attaches to downloaded files):

         xattr -dr com.apple.quarantine ~/html-py-editor-paket

   If it looks different:
   - “No such file or directory” after the ditto command:
     a) Safari has already unpacked the ZIP file itself. In the “Downloads” folder there is then a folder
        “html-py-editor” instead of the ZIP file. Enter this instead:

           ditto ~/Downloads/html-py-editor ~/html-py-editor-paket/html-py-editor

        and then the xattr command from step 4.
     b) The file has a different name, e.g. “html-py-editor (1).zip”, because you downloaded it twice.
        Rename it to “html-py-editor.zip” in the Finder (delete older files of the same name first) and
        repeat step 3.
   - “Operation not permitted”: Open “System Settings” › “Privacy & Security” ›
     “Files & Folders”, expand “Terminal” and switch on “Downloads Folder”.
     Then repeat step 3.

B4. Install modules (once only, 1 to 3 minutes)
   1. In the Terminal, enter this command:

         bash ~/html-py-editor-paket/html-py-editor/module-installieren.sh

   2. You see “Python found: …”, then “Step 1 of 3” to “Step 3 of 3” and many lines.
      Wait until the line ending in  %  appears again.
   3. At the end it says “SFTP (paramiko): ready” and “Done.” together with the command for starting.

   If it looks different:
   - “Python 3.8 or newer was not found on this computer”: Do B2. Then close the Terminal window, open a
     new one and repeat B4.
   - “The installation did not work”: Check your internet connection and repeat B4.

B5. Start the editor (every time)
   1. Open the Terminal (section 3) and enter this command:

         bash ~/html-py-editor-paket/html-py-editor/html-py-editor-starten.sh

   2. The Terminal shows a line “Editor: http://127.0.0.1:8790/”, and Chrome opens the editor.
   3. Leave the Terminal window open while you work. You can minimise it to the Dock (yellow button).
   4. To quit, close the Terminal window (red button at the top left) and confirm with “Terminate”.
      Or you press control + C in the Terminal.

   Tip: Next time, in the Terminal just press the ↑ arrow key (until the command appears) and the
   Return key.
   Tip: After step B3 you can also double-click “HTML-PY-Editor starten (macOS).command” in the Finder
   (home folder › “html-py-editor-paket” › “html-py-editor”). If macOS says the file cannot be opened,
   use the command from step 1 – it always works.

   Continue with section 4 (“How to check that it worked”).


Part C – Linux
==============
   The commands apply to Ubuntu, Linux Mint and Debian. For other systems the matching command is given
   underneath. How to open the Terminal and enter commands is explained in section 3.

C1. Install Python and the module for separate environments (once only)
   1. Enter in the Terminal (it will then ask for your password):

         sudo apt install python3 python3-venv

      If it asks “Do you want to continue? [Y/n]”, press Y and the Enter key.
      Fedora:     sudo dnf install python3
      openSUSE:   sudo zypper install python3
      Arch:       sudo pacman -S python

C2. Install a browser (if neither Chrome nor Chromium is present)
   1. Install Google Chrome from   https://www.google.com/chrome/   or Chromium via your system's
      software manager.

C3. Download and unpack the package
   1. Download “html-py-editor.zip” into the “Downloads” folder.
   2. Enter in the Terminal:

         python3 -m zipfile -e ~/Downloads/html-py-editor.zip ~/html-py-editor-paket

C4. Install modules (once only)
   1. Enter in the Terminal:

         sh ~/html-py-editor-paket/html-py-editor/module-installieren.sh

   2. Wait until “Done.” appears.

C5. Start the editor (every time)
   1. Enter in the Terminal:

         sh ~/html-py-editor-paket/html-py-editor/html-py-editor-starten.sh

   2. Chrome or Chromium opens the editor. Leave the Terminal open; quit with Ctrl + C.

   Note: On Linux the editor saves passwords only if your desktop has a keychain (e.g. GNOME or KDE).
   Otherwise you enter the password once each time you start.


4. How to check that it worked
------------------------------
   1. In the black window (Windows) or in the Terminal (Mac, Linux), these lines appear at the top:
        SFTP:          ready (paramiko)
        Keychain:      ready (keyring)
      If SFTP says “not available”, repeat the module installation (A3, B4 or C4).
   2. In the browser you see “Welcome to the HTML-PY-Editor” with the buttons “Create new website…” and
      “Open existing project…”. A red line “The Python program is not connected” must not be there.
   3. Later, in the “Upload” tab, “✓ Connected to the Python program” and “SFTP ✓” appear at the top
      in green.


5. First steps in the editor
----------------------------
   1. Click “Create new website…”, enter the name of your website, choose a template and click “Create”.
   2. Choose an empty folder (or create a new one in the selection window, e.g. “my-website” in
      “Documents”). If the browser asks whether the editor may view this folder and save in it, agree.
      (You open projects of the FreeHTML-Editor with “Open existing project…”.)
   3. Design the colours, menu, pages and blog. Then click “⚙ Generate website”.
   4. In the “Upload” tab: choose the method (SFTP recommended), enter server, port, user and directory,
      then click “Test connection”. On the first SFTP contact the editor shows the fingerprint of the
      server – if possible, compare it with the details from your hosting provider.
   5. “Check what will be uploaded” and then “⬆ Upload”. Next time only what is new or changed is uploaded.
   6. Several languages (⚙ Settings › Languages): Each additional language is kept in a folder of its own in
      the website (e.g. “en”); all language folders are uploaded automatically, together with their file
      “.htaccess”. If you create a new page, post or menu item, it is created in all languages – in the
      others as a copy marked “Translation pending” until you translate it. A copy only goes online once
      you set it to “published”.
   7. Language of the editor: At the top right, “DE | EN” switch the interface between German and English.
      Your website does not change as a result.


6. Common problems and solutions
--------------------------------
   “Python was not found” or “Python 3.8 or newer was not found …”
      Python is not installed, or the window was opened before you installed it. Install Python (A1 or
      B2), close the black window or Terminal and start again.

   Windows: When you type “python”, the Microsoft Store opens
      That is only a placeholder from Windows, not an installed Python. Install Python as in A1.

   Mac: A window offers “command line developer tools”
      Click “Cancel” and install Python as in B2. The tools are not needed.

   Mac: The .command file cannot be opened by double-clicking (“… cannot be opened”,
   “Apple could not verify …” or “You do not have permission to open the application …”)
      Use the command in the Terminal (B4 or B5). It always works, even without double-clicking.

   “The installation did not work” or many red lines during the module installation
      Usually the internet connection is missing or a company network blocks access. Check the connection
      and repeat the step. The editor also works without the modules; you can then upload via FTPS
      instead of SFTP.

   The editor opens in Safari or Firefox, or it reports “This browser does not support folder access”
      Copy the address from the black window or Terminal (e.g. http://127.0.0.1:8790/) into the
      address bar of Google Chrome or Microsoft Edge. If Chrome is missing: B1.

   The editor says “The Python program is not connected”
      You opened the file “html-py-editor.html” directly. Close the browser tab and start
      the editor via the start script (A4, B5 or C5).

   “No free port between 8790 and 8799”
      Is the editor already running in another window? Then use that one. Otherwise restart the computer.

   Mac with macOS 12 or older: Chrome reports that it no longer receives updates
      The editor runs anyway. Update macOS if your Mac allows it (section 2).

   The password is not saved
      If “Keychain: not available” appears at the top, the keyring module is missing (repeat the module
      installation) or – on Linux – your desktop has no keychain. Then you enter the password once
      each time you start.


7. Removing (uninstalling)
--------------------------
   Windows:
   1. Close the black window of the editor.
   2. Delete the folder “html-py-editor” (right-click › “Delete”).
   3. Optional: In File Explorer, type   %APPDATA%   into the address bar at the top and press the
      Enter key. Delete the folder “HTML-PY-Editor” there (saved upload status files).
   4. Optional: saved passwords: Press the Windows key, type “Credential Manager”,
      Enter key › “Windows Credentials” › entries with “HTML-PY-Editor” › “Remove”.
   5. Optional: Python itself: “Settings” › “Apps” › “Installed apps” (Windows 10: “Apps &
      features”) › “Python 3.…” › “Uninstall”. The same applies to “Python Launcher”.

   Mac:
   1. Close the Terminal window of the editor.
   2. In the Finder, drag the folder “html-py-editor-paket” from your home folder to the Trash.
      (You open the home folder in the Finder via “Go” › “Home”.)
   3. Optional: Finder › “Go” › “Go to Folder…”, type
         ~/Library/Application Support/HTML-PY-Editor
      and press the Return key. Drag the folder to the Trash.
   4. Optional: saved passwords: cmd + Space, type “Keychain Access”, Return key,
      search for “HTML-PY-Editor” at the top right, right-click the entry › “Delete …”.
   5. Optional: Python itself: Finder › “Applications” › drag the folder “Python 3.…” to the Trash. Then
      Finder › “Go” › “Go to Folder…”, type
         /Library/Frameworks/Python.framework/Versions
      and drag the folder with the version number (e.g. “3.15”) to the Trash (it asks for your
      password). However, Python may also stay; it does no harm.

   Linux:
   1. Close the Terminal of the editor or press Ctrl + C.
   2. Delete the folder “html-py-editor-paket” and “~/.config/HTML-PY-Editor”.
   3. Optional: saved passwords in “Passwords and Keys” (GNOME) or KWallet (KDE).


8. Good to know
---------------
   - The program can only be reached on your own computer (address 127.0.0.1) and accepts only requests
     from the editor page that it opened itself. It transmits nothing to the publisher or to third parties;
     it only talks to the server that you enter yourself.
   - Passwords are never in the project. With the keyring module you can save them in the keychain of your
     operating system; otherwise you enter them once each time you start.
   - On the server, at most files are deleted that were previously uploaded from this computer and no longer
     appear in the website (tick box “Delete previously uploaded files …”) – never other people's files.
   - What has already been uploaded is remembered by the program in your user folder:
       Windows: %APPDATA%\HTML-PY-Editor     Mac: ~/Library/Application Support/HTML-PY-Editor
       Linux:   ~/.config/HTML-PY-Editor
     That is also where “bekannte-server.json” (= known servers) with the confirmed fingerprints of the
     servers is kept.
   - The messages in the black window or Terminal appear in German if your computer is set to German,
     otherwise in English. To fix the language: environment variable HTMLPY_SPRACHE=de or =en.
   - For advanced users: another port number with “--port 8800” after the start command; “--kein-browser”
     (= no browser) opens no browser. Manual installation: in the package folder  python3 -m venv .venv
     and then  .venv/bin/python3 -m pip install --prefer-binary -r requirements.txt  (Windows:
     py -m venv .venv and .venv\Scripts\python.exe -m pip install --prefer-binary -r requirements.txt).
   - Why “--prefer-binary”? For Macs with an Intel processor, some modules are no longer available ready-built
     in their latest version. With this option pip takes the latest ready-built version instead of trying
     to build the module itself – which would fail without developer tools.
