Skip to content

Latest commit

 

History

History
41 lines (34 loc) · 4.84 KB

README.md

File metadata and controls

41 lines (34 loc) · 4.84 KB
Raw

STATIC SITE GENERATOR

Video Demo: https://youtu.be/VO1nb8HD-9U

Description:

This project written in python is a simple tool that will convert markdown files into html, creating a nice website :).

Motivation
I have always wanted a middleground between writing html myself and a full cms like wordpress. I have used these two systems in the past but the first is not very good for scalability and the second one always presents the challenge of maintaining a wordpress instance and fighting with templates to get them to do what you want, it is very heavy duty and "easy" for my taste.
I then discovered some existing static site generators but unfortunately they didn't work very well for me, so I decided to write one that would just suit my needs and no more, that could be extended easily and customized.

Architecture
This project in itself only consists of a python file, a html file and a db file, that is all you need.
Of course, there is more to it than just this:

  1. The python file app.py, contains the code for the application naturally and will be explained further in the document
  2. The db file will be generated by the app.py file, it is a simple database that will hold some "metadata" needed for our app to work smoother, described in more detail below.
  3. The template, currently located in templates/base.html, (although it can be parametrized easily) will be the html template in which the code will be inserted
  4. The markdown_files directory contains the markdown files that the application will take as input
  5. The html directory contains the html files that result as output of the application, and will later be served with any file/web server

How it works
The general idea is that given a directory with files, we will iterate over all of those and evaluate wether this file has changes from the last time the program was executed or not. In a positive case, we will convert the file to html and save the result

  • The arguments: The project as per writing this document only receives one argument, that is, the path to the directory that contains the markdown files.
  • The Class: the program is one class that contains multiple methods, the class receives the argument passed in the previous step
    • init: set some variables, the path, opens the sql connection and "empties" the navbar
    • start: this function is called from outside the class, it only executes the list_files() method
    • close: this function is called from outside the class, it only closes the sqlite connection
    • list_files(): for each file in the markdown directory, it checks if it is a mardown file and executes the file_details(x), where x is the current file we are looking at in a certain iteration
    • file_details(i): where i is the specific file we are looking at this function extracts the details of the file using the stat function, calls the generate_nav(i) and the aligned(i) method
    • aligned(details, file_name): will trigger the database to see if the file already exists in the db. If it does not exist, then it is a new file and we need to insert something into the db, using the insert() funtion and generate the html using the md_to_html() funtion. If the file exists then there are two cases. Either the timestamp recorded in the db is the same as the current one of the file, in this case the file has not changed and we take no action. Otherwise, the file has changed so we execute the update() function and the md_to_html file
    • insert(file_name, detail): executes a query in the db to insert the file_name and the associated timestamp
    • update(file_name, detail): executes a query in the db to update the timestamp for the file_name
    • md_to_html(directory, file): reads the file, converts it with Marko, uses templating with Jinja and saves the output
    • generate_nav(file): uses templating to generate a particularly formatted html tag and thus generate a working navbar

Libraries used

  1. Marko: this one helps me convert the files from .md to .html syntax
  2. jinja2: Now, the html produced by marko is not "plain", it will use a html template to make it nicer :). I have personally chosen the cover template from bootstrap to be the template here for simplicity and I have retrieved the html, css code from the template and included very basic blocks to make it work. Please note that support for several templates can bee added very easily and probably will be done soon
  3. sqlite3: this is the interface I have chosen for a little db, instead of the one provided by cs50.

it was challenging to learn new libraries, each of them have their singularities but the documentation was overall very helpful. I only struggled a little bit with the sqlite3 lib.