https://github.com/crisfeim/cli-swiftdown
🛠️ A Swift-based article generator for technical writing in .swift files. Comments become prose. Code stays as code.
https://github.com/crisfeim/cli-swiftdown
code-documentation static-site-generator swift-cli technical-writing
Last synced: 2 months ago
JSON representation
🛠️ A Swift-based article generator for technical writing in .swift files. Comments become prose. Code stays as code.
- Host: GitHub
- URL: https://github.com/crisfeim/cli-swiftdown
- Owner: crisfeim
- License: other
- Created: 2025-05-07T21:56:29.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-06-16T02:58:01.000Z (6 months ago)
- Last Synced: 2025-06-16T04:15:04.679Z (6 months ago)
- Topics: code-documentation, static-site-generator, swift-cli, technical-writing
- Language: Swift
- Homepage:
- Size: 2.43 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swiftdown
> Because Markdown was too mainstream.
**Swiftdown** lets you write entire technical articles using Swift files. Comments become prose. Code stays as code.
## Motivation
Writing in Markdown is fine. But for developers writing about Swift, it's disconnected. Swiftodwn keeps everything in the same medium:
- Write and explain code using `//` comments.
- Structure your article using code blocks.
- Export to HTML in one command.
All within the comfort of a `.swift` file.
## Features
- `//` and `///` comments are treated as narrative content.
- Code blocks are preserved with syntax highlighting.
- Generates a standalone `.html` file (no assets or dependencies).
- Command-line usage.
## 📹 Demo
https://github.com/user-attachments/assets/1558827f-cb87-45d3-92f6-f3ecb8680c7f
## 📦 Installation
Clone this repo and build:
```bash
git clone https://github.com/crisrojas/swiftdown
cd swiftdown
swift build -c release
```
Then add the binary to your path or use directly from .build/release/swiftdown.
## Usage
You need to structure your project as follows:
```
|- your-swift-blog
|- sources
|- theme
```
For an example theme see `example` folder.
Then pass it to the CLI
```bash
~ swiftdown build your-swift-blog
```
Alternatively, you can also serve the contents:
```bash
~ swiftdown serve your-swift-blog
```
## 🧑💻 Use Cases
- Technical blog posts written entirely in Swift.
- Annotated code walkthroughs.
- Educational examples and tutorials.
- Reproducible code + prose workflows for teams.
## 🛣️ Roadmap
This project started as an experiment. I was tired of copy-pasting code from playgrounds into articles. I thought: why not write articles in Swift, using Swift itself?
The idea has merit, and some real utility, but also caveats.
Still, Swiftdown is mostly feature-complete. If I ever revisit it, I’d like to add:
- Export to self-contained .html articles `swiftdown Article.swift > article.html`
- Project navigation, displaying files and folders with their icons.
And overall, a more Xcode-like look and feel. Imagine pointing it at your whole project and having it rendered — wouldn’t that be cool?
## License
MIT — You are free to use, modify, and distribute this project. Attribution is required.
## Credits
- Theme toggle styles adapted from [theme-toggles](https://github.com/AlfieJones/theme-toggles) by Alfred Jones — MIT License.
- Syntax highlighting provided by [Splash](https://github.com/JohnSundell/Splash) by John Sundell.