bhodrolok / rupantar

🐍 Simple Python-based Static Site Generator 📝

Rupantar

No-frills website generation, powered by Python

/ɾuːpɑnˈtɔɾ/ (Bengali)

transformation

---

Table of Contents 🚩

1. Description
2. Features
3. Dependencies
4. Installation
5. Usage
1. Quick Demonstration
6. Project Structure
7. Configuration
8. Contributing
9. License

---

Description 🌾

Fork of pidgeotto

Rupantar is a command-line tool that enables quick generation of simple, minimally themed, static websites with extensive support for customizations.

(back to top ⬆️ )

Features 🚀

1. Customizable templates using Jinja2
2. Fits well with multiple use cases
   • Blogging, personal knowledge base, portfolio, etc.
3. Fully JavaScript-free
   • Trust the resilience of good ol' HTML and CSS
4. RSS and Atom feed generation
5. Fast build times
6. Bundled web server with live reload on changes
7. Cross-platform
   • Runs in Windows, Linux, and macOS machines
8. Minimal system resource usage/footprint

(back to top ⬆️ )

Dependencies 🌉

Rupantar has the following dependencies:

• PyYAML: Project configuration and page metadata management

• tomli: Same as above for TOML enjoyers

  • Not required if running Python 3.11 or above

• jinja2: Templating engine used to render the HTML/XML pages

• markdown2: Reading Markdown files

• xdg-base-dirs: Getting location for app runtime data storage ('AppData')

  • as per the XDG Base Dir spec
  • mostly for storing logs when running rupantar

(back to top ⬆️ )

Installation 🥥

• Rupantar needs Python installed locally.

  • CPython version compatibility: Python interpreter version 3.10 or higher.

• pip, Python's default package management tool, can be used.

• If pipx is available, it is recommended to use that instead.

• Installation from source:

  • Install Git
  • Clone this git repository
  • cd into the rupantar directory

    $ pip install -r requirements

• Direct installation using Git:

    $ pip install git+https://github.com/bhodrolok/rupantar

• Using pipx:

    $ pipx install rupantar==0.9.5a0

(back to top ⬆️ )

Usage 🦀

• NB: Rupantar is a pure CLI tool, without any GUI.

To get a comprehensive list of commands and options:

$ rupantar -h

To get the detailed usage of a specific command:

$ rupantar cmd_name -h

(back to top ⬆️ )

Quick Demo 💈

To initiate a project ( say for example notun):

$ rupantar init notun

• NB: Some generic questions will be asked running this command in order to set up some configuration values.
• To avoid this, pass the -s or --skip flag after init.
  • They will be filled with some sane defaults.

To add a new post/page (say for example kagoch, to the existing notun project):

$ rupantar new notun kagoch

To build the static pages (for notun):

$ rupantar build notun

To preview the website locally:

$ rupantar serve notun

• Useful for quick and simple testing via a local HTTP web server.

(back to top ⬆️ )

Project Structure 🍴

The overall skeleton of a fully built & ready-to-serve rupantar project looks something like:

rupantar_project/
    ├── config.yml  <-- Config for the page title, CSS file, and other custom config (custom templates, etc.)
    ├── content/  <-- Directory to store Markdown files.
    │   ├── header.md
    │   ├── footer.md
    │   ├── home.md
    │   └── notes/  <-- Directory to store Markdown files for content of extra pages.
    │       └── example_blog.md
    └──static/  <-- Directory to store static content eg: CSS, images, etc.
    │   └── demo.css
    ├── public/   <-- Directory to store the generated static site.
    └── templates/  <-- Directory to store Jinja2 layouts for the pages.
        ├── home_template.html.jinja
        ├── note_template.html.jinja
        ├── your_custom_template.html.jinja
        └── feed_template.xml.jinja

Rupantar itself is developed with a "src layout" structure so as to follow a more modern, standardized, and organized way of managing everything. To read more about that, click here.

A 🚧 features roadmap of this Python project can be found here.

And lastly, there is also a TODO.md for some transparency and organization (and quick notes/documentation :P).

(back to top ⬆️ )

Development & Configuration 🍽️

• It is recommended to use Poetry for better dependency management, packaging, and release.

  • A big reason is the ease in managing virtual environments.
  • Why consider venvs in the first place? Well you get an isolated environment, better reproducibility, better dependency management, and (most importantly!) minimize risk of any conflicts with other existing Python projects/dependencies locally on the system. Especially if they were installed globally system-wide using pip.
  • Just overall makes the development process more smoother.

• After forking and cloning the repository:

  • Navigate to the cloned project directory.
  • Install all the dependencies, including the optional ones:

    $ poetry install --with=dev,test,docu

  • Activate a virtual env:

    $ poetry shell

  • Run rupantar:

    $ poetry run rupantar -h

(back to top ⬆️ )

Contributing 📜

This is an open source project. Suggestions, bug reports, feature requests, documentation improvements, etc. are more than welcome through Pull Requests (PRs) and Issues.

The usual steps for contributing via a PR are:

1. Fork this repository to your own GitHub account

2. Clone the repository to your machine

$ git clone https://github.com/Bhodrolok/rupantar.git

3. cd to where you cloned the repo and create a local git branch

$ git checkout -b new-feature-branch

4. Make your changes and commit them to that branch

$ git commit -m "brief description about changes"

5. Push your changes to your remote fork

$ git push origin new-feature-branch

6. Create a new Pull Request!

(back to top ⬆️ )

License 🔖

This project is licensed under the MIT License.

tldr is that rupantar is Free and Open Source Software (FOSS)!

(back to top ⬆️ )

Similar Projects 🐐

• pidgeotto - Primary inspiration for this project.
• Pelican - Python-based
• Jekyll - Ruby-based
• Hugo - Go-based
• Zola - Rust-based
• Eleventy - JavaScript-based alternative to Jekyll
• Some more Python-based static site generators can be found here.

(back to top ⬆️ )