markdown2app 0.1.4

libs to run markdown as an app in a python3 environment

markdown2app

markdown2app.plainmark.com

Plainmark

Plainmark is a lightweight programming language embedded in Markdown that runs across multiple platforms including web browsers, terminal environments, desktop applications, and mobile devices.

What is Plainmark?

Plainmark allows you to write both documentation and executable code in the same Markdown file. Code blocks tagged with ```plainmark are interpreted and executed by the Plainmark runtime.

Key Features

• Write Once, Run Anywhere: The same Plainmark code works across all supported platforms
• Embedded in Markdown: Combine documentation and executable code in a single file
• Platform-Specific APIs: Access platform capabilities like file system, device sensors, etc.
• Interactive Documents: Create dynamic, interactive documentation
• Easy to Learn: Familiar JavaScript-like syntax

Platform Implementation Guide

Browser Implementation

The browser implementation uses JavaScript to interpret and execute Plainmark code. It consists of:

1. An HTML file that provides the editor interface
2. A JavaScript interpreter that extracts code blocks and executes them
3. DOM manipulation capabilities for UI rendering

Running in Browser:

1. Open index.html in any modern browser
2. Write your Plainmark code in the editor
3. Click "Run" to execute

Terminal/Python Implementation

The Python implementation allows running Plainmark in any terminal environment. It consists of:

1. A Python script (plainmark.py) that processes Markdown files
2. A code extractor and interpreter for Plainmark code blocks
3. Python-based API for file system access and terminal commands

Running in Terminal:

# Execute a file
python plainmark.py example.md

# Start REPL mode
python plainmark.py --repl

# Create an example file
python plainmark.py --example

Desktop Implementation (Electron)

The desktop implementation provides a native application experience using Electron. It consists of:

1. A main process (main.js) that handles application lifecycle
2. A renderer process (index.html) with the editor UI
3. IPC communication for file operations
4. Full system access through Node.js APIs

Building for Desktop:

# Install dependencies
npm install

# Run in development mode
npm start

# Build for distribution
npm run build

Mobile Implementation (Android)

The Android implementation runs Plainmark on mobile devices. It consists of:

1. A Kotlin-based Android app
2. A WebView for executing Plainmark code
3. JavaScript interfaces for accessing device features (camera, sensors, etc.)
4. Integration with the Android filesystem

Building for Android:

1. Open the project in Android Studio
2. Connect an Android device or start an emulator
3. Build and run the app

Plainmark Syntax Examples

Basic Syntax

# My Plainmark Program

This is a simple program.

```plainmark
// Variables
let name = "World";
let number = 42;

// Output
print("Hello, " + name + "!");
print("The answer is: " + number);

### Platform-Specific Features

```markdown
# Cross-Platform Example

```plainmark
// Detect platform
let platform;
if (typeof window !== 'undefined' && window.Android) {
  platform = "Android";
} else if (typeof process !== 'undefined' && process.versions.electron) {
  platform = "Desktop";
} else if (typeof document !== 'undefined') {
  platform = "Browser";
} else {
  platform = "Terminal";
}

print("Running on: " + platform);

// Use platform-specific features
if (platform === "Android") {
  // Mobile-specific code
  let acceleration = JSON.parse(readSensor("accelerometer"));
  print("Device acceleration: " + acceleration.x + ", " + acceleration.y + ", " + acceleration.z);
} else if (platform === "Desktop") {
  // Desktop-specific code
  let sysInfo = getSystemInfo();
  print("CPU cores: " + sysInfo.cpus);
} else if (platform === "Browser") {
  // Browser-specific code
  document.body.innerHTML += "<div>Running in browser!</div>";
} else {
  // Terminal-specific code
  print("Current directory: " + executeCommand("pwd"));
}

## Use Cases

- **Educational tools** - Interactive learning materials and tutorials
- **Documentation** - Self-executing technical documentation
- **Prototyping** - Quick application development across platforms
- **Note-taking** - Executable notes and code snippets
- **Data analysis** - Process and visualize data in Markdown



# Plainmark - Instrukcja instalacji i pierwsze kroki

Plainmark to język programowania osadzony w Markdown, który pozwala na uruchamianie kodu na różnych platformach. Poniżej znajdziesz instrukcje, jak zainstalować i używać Plainmark na różnych urządzeniach.

## Spis treści

1. [Instalacja](#instalacja)
   - [Przeglądarka](#przeglądarka)
   - [Terminal (Python)](#terminal-python)
   - [Aplikacja desktopowa](#aplikacja-desktopowa)
   - [Urządzenia mobilne (Android)](#urządzenia-mobilne-android)
2. [Pierwsze kroki](#pierwsze-kroki)
3. [Struktura pliku Plainmark](#struktura-pliku-plainmark)
4. [Przykłady](#przykłady)
5. [Rozwiązywanie problemów](#rozwiązywanie-problemów)

## Instalacja

### Przeglądarka

Najłatwiejszym sposobem na rozpoczęcie pracy z Plainmark jest użycie wersji przeglądarkowej:

1. Pobierz plik `index.html` z repozytorium
2. Otwórz go w dowolnej nowoczesnej przeglądarce (Chrome, Firefox, Safari, Edge)
3. Gotowe! Możesz zacząć pisać i uruchamiać kod Plainmark

### Terminal (Python)

Aby uruchomić Plainmark w terminalu, potrzebujesz Pythona 3.6 lub nowszego:

1. Pobierz plik `plainmark.py` z repozytorium
2. Upewnij się, że masz zainstalowanego Pythona 3.6+
3. Uruchom interpreter w jednym z trybów:

```bash
# Wykonanie pliku Plainmark
python plainmark.py przyklad.md

# Tryb interaktywny
python plainmark.py --repl

# Utworzenie przykładowego pliku
python plainmark.py --example

Web

cd web

1. Użyj portu powyżej 1024 (najlepiej powyżej 8000):

   python -m http.server 8080
   

2. Używaj poprawnej składni - port podaje się bezpośrednio jako pierwszy argument:

   python -m http.server 8888
   

3. Jeśli port jest zajęty, możesz:

   • Użyć innego portu (np. 8001, 8080, 9000)
   • Zakończyć proces używający danego portu:

     # Znajdź proces używający portu 8000
     sudo lsof -i :8000
     # albo
     netstat -tuln | grep 8000
     
     # Zakończ proces (zastąp PID numerem procesu)
     kill PID
     

Spróbuj wykonać:

python -m http.server 8888

A następnie otwórz w przeglądarce adres:

http://localhost:8888

Jeśli nadal masz problemy z uruchomieniem serwera HTTP, możesz także wypróbować inne rozwiązania:

1. Użyj innego serwera HTTP, np. Node.js:

   npx serve
   

2. Użyj PHP (jeśli zainstalowane):

   php -S localhost:8888
   

3. Sprawdź, czy masz uprawnienia do zapisu w katalogu, w którym próbujesz uruchomić serwer.

Aplikacja desktopowa

Instalacja aplikacji desktopowej (bazującej na Electron):

1. Sklonuj repozytorium:

   git clone https://github.com/plain-mark/markdown2app.git
   cd markdown2app/desktop
   

2. Zainstaluj zależności:

   npm install
   

3. Uruchom aplikację:

   npm start
   

4. (Opcjonalnie) Zbuduj aplikację dla swojego systemu:

   npm run build
   

Urządzenia mobilne (Android)

Aby zainstalować Plainmark na urządzeniu Android:

1. Pobierz plik APK z repozytorium lub sklepu Google Play
2. Uruchom plik APK na swoim urządzeniu
3. Zaakceptuj wymagane uprawnienia (dostęp do plików, kamera, itp.)
4. Aplikacja jest gotowa do użycia!

Alternatywnie, możesz zbudować aplikację z kodu źródłowego:

1. Sklonuj repozytorium:

   git clone https://github.com/plain-mark/markdown2app.git
   

2. Otwórz folder android w Android Studio

3. Zbuduj i uruchom aplikację na emulatorze lub fizycznym urządzeniu

Pierwsze kroki

Po zainstalowaniu Plainmark, czas na pierwszy program:

1. Utwórz nowy plik tekstowy o rozszerzeniu .md (np. pierwszy.md)
2. Wpisz następującą treść:

# Mój pierwszy program Plainmark

To jest prosty program, który wyświetla powitanie.

```plainmark
// Zdefiniuj zmienną
let name = "Świat";

// Wypisz powitanie
print("Witaj, " + name + "!");

// Utwórz prosty element interfejsu (w przeglądarce lub na urządzeniu mobilnym)
if (typeof document !== 'undefined') {
  let greeting = document.createElement("div");
  greeting.textContent = "Witaj, " + name + "!";
  greeting.style.padding = "10px";
  greeting.style.backgroundColor = "#e0f7fa";
  greeting.style.borderRadius = "5px";
  greeting.style.marginTop = "10px";
  
  document.body.appendChild(greeting);
}

Uruchom program!

3. Uruchom plik w wybranym środowisku:
   - **Przeglądarka**: Wklej kod do edytora i kliknij "Uruchom"
   - **Terminal**: `python plainmark.py pierwszy.md`
   - **Aplikacja desktopowa**: Otwórz plik w aplikacji i kliknij "Uruchom"
   - **Android**: Wklej kod do edytora aplikacji i kliknij "Uruchom"

## Struktura pliku Plainmark

Każdy plik Plainmark składa się z dwóch głównych elementów:

1. **Tekst w formacie Markdown** - dokumentacja, opisy, instrukcje
2. **Bloki kodu Plainmark** - wykonywalne fragmenty kodu

Bloki kodu są oznaczone przez trzy backticki z identyfikatorem języka `plainmark`:

````markdown
# Tytuł dokumentu

Opis w formacie Markdown.

```plainmark
// Ten kod zostanie wykonany
let x = 10;
print("Wartość x: " + x);

Więcej tekstu w Markdown.

## Przykłady

### Obsługa zmiennych i funkcji

```markdown
# Zmienne i funkcje

```plainmark
// Definiowanie zmiennych
let name = "Jan";
let age = 30;
let isActive = true;
let items = [1, 2, 3, 4, 5];
let person = {
  firstName: "Jan",
  lastName: "Kowalski",
  age: 30
};

// Definiowanie funkcji
function greet(name) {
  return "Witaj, " + name + "!";
}

// Użycie funkcji
let greeting = greet(name);
print(greeting);

// Wypisanie informacji o osobie
print("Imię: " + person.firstName);
print("Nazwisko: " + person.lastName);
print("Wiek: " + person.age);

// Pętla po tablicy
print("Elementy tablicy:");
for (let i = 0; i < items.length; i++) {
  print("- " + items[i]);
}
```
```

### Obsługa DOM (w przeglądarce i na urządzeniach mobilnych)

```markdown
# Manipulacja DOM

```plainmark
// Sprawdź, czy DOM jest dostępny
if (typeof document !== 'undefined') {
  // Utwórz element
  let button = document.createElement("button");
  button.textContent = "Kliknij mnie!";
  button.style.padding = "10px 20px";
  button.style.backgroundColor = "#4285f4";
  button.style.color = "white";
  button.style.border = "none";
  button.style.borderRadius = "4px";
  button.style.cursor = "pointer";
  
  // Dodaj obsługę zdarzenia
  let clickCount = 0;
  button.addEventListener("click", function() {
    clickCount++;
    print("Przycisk został kliknięty " + clickCount + " razy.");
  });
  
  // Dodaj element do strony
  document.body.appendChild(button);
  
  print("Przycisk został dodany do strony. Kliknij go!");
} else {
  print("DOM nie jest dostępny w tym środowisku.");
}
```
```

## Rozwiązywanie problemów

### Problem: Kod nie uruchamia się w terminalu (Python)

**Rozwiązanie**: Upewnij się, że:
- Używasz Python 3.6 lub nowszego
- Kod w blokach jest zgodny z składnią Python (bez średników na końcu linii)
- Bloki kodu są prawidłowo oznaczone jako ```plainmark

### Problem: Funkcje specyficzne dla platformy nie działają

**Rozwiązanie**: Zawsze sprawdzaj dostępność API przed jego użyciem:

```plainmark
// Przykład sprawdzania dostępności API
if (typeof document !== 'undefined') {
  // Kod specyficzny dla przeglądarki/urządzenia mobilnego
} else if (typeof fs !== 'undefined') {
  // Kod wykorzystujący system plików
} else {
  print("Ta funkcja nie jest dostępna w bieżącym środowisku.");
}
```

### Problem: Błędy składniowe w różnych środowiskach

**Rozwiązanie**: Pamiętaj, że:
- W przeglądarce i na Androidzie kod jest uruchamiany jako JavaScript
- W terminalu kod jest konwertowany na Python
- Używaj wspólnego podzbioru składni dla maksymalnej kompatybilności

---

Więcej informacji można znaleźć w pełnej dokumentacji Plainmark dostępnej na stronie projektu.