So what is the new website going to be?

Last week I discussed some of my experiences with various static site generators, and my motivation for moving away from them. This week, I discuss where I am headed.

Considerations

First, I have to consider the fact that I love Python and am very comfortable in it. There are plenty of Python-based web frameworks, including Flask, Fast API, and Django. I really haven't used any of them, though.

Second, I have to consider some of my potential use cases. What do I want to do with my website?

• I still want to be able to write in Markdown.
• I potentially want a different user experience for someone who is logged in versus someone who isn't, or for someone who is a subscriber or is not.
• I also want to play with different kinds of interactions. This might include JavaScript based plots, figures, games, or quizzes. It might also include the ability to interact with virtual terminals, or coding environments such as a Python/Jupiter notebook like experience.
• Perhaps someday I might want a payment portal, sell a product, or perhaps a subscription.
• I either want a toolset that I have more control over, in terms of versioning, access to and knowledge of the source code... Or the exact opposite, with a batteries included experience that I don't have to think about at all.
• I want to be able to start small and grow the site as my needs grow and my knowledge of what I need becomes more concrete.
• I'd like to be able to host the site on my own computer during development, but also deploy it to a third-party server without needing a PhD in IT.
• I want it to be able to play nice on the back end with other Python tools, because I'm such a heavy Python user. It has to be a Python environment for me.

My choices so far

So what are some of the things that I've selected?

Django for the framework

I'm going to go with Django because it has a very long track record. I also know that I'm not relatively strong in database management, and Django automates the creation and maintenance of the basic data types of your website.

Django also automates the creation of the administration side of your website, which I have found really appealing. I like how, with minimal effort, Im able to create a new data type and add or remove new instances of that type all from the web interface.

Docker for portability

I'm going to create my Django site within Docker. Since my early days of trying to use Docker and Jekyll together, I've become a bit more of an expert in how to create and maintain custom Docker images. I've also come to appreciate the ability of Docker to be tied to specific image versions, which would help me control when or where I upgrade specific parts of my site. Thirdly, Docker Compose files are really good at setting up complex interdependencies that, once working, don't seem to break that often. I have certainly had gripes relating to some of Docker's idiosyncrasies, but I've gotten over many of them just by digging into complex corner cases and figuring out how it works.

Docker will also allow me to create a working instance on my local computer that mirrors the final version that I deploy on a third-party site. Hopefully this will make me less dependent on whatever third-party host I select.

Markdown at the gooey center

Core to my website update would be the inclusion of markdown functionality.

Django does not play with markdown at all, and though I know that there are some django derivatives out there that allow you to combine the two, my worry is that, given some of my other needs, they won't do exactly what I want. So for now I'm going to use the same Markdown to HTML conversion tool that MkDocs uses, which is the python-markdown library. More on how I solved that problem in an upcoming article.

Other needs: functional code blocks

In terms of website functionality, I think my most important functional addition is going to be how to render the embedded code within my markdown, and control its presentation. I would like code to have the option to be numbered, to be copyable, and to be able to control the formatting and color of my code separately from the rest of the page.

Search -- an open question

I'm going to want to include some sort of search tool. After including it in the previous iteration of my website, I found it to be invaluable for finding my own content. I know that Django provides an easy way to search, and I will try that, but I appreciated the fuzzy nature of my previous search tool and may just keep that for now. That means that instead of implementing search, I will need to implement some sort of JSON view of my site

Database selection: MariaDB for now

In terms of database, I'm going for now with MariaDB, and SQLite for internal development. I don't work with databases directly that often, but I will manage if I can select a database that is well documented and has a large community of people who have had similar problems as me. Picking a database that also has lots of support tools such as MySQL derivatives is probably a smart choice too.

Styling: Bootstrap for continuity

In terms of CSS frameworks, I am sheepishly going to stick with Bootstrap, though I will be upgrading to Bootstrap 5. Right now I don't want to learn something new in CSS. I just want something that I sort of understand and can deploy quickly.

Other Considerations

In terms of other functionality, coming from academia, I will still probably want some sort of math environment like MathJax. I might want some sort of formal referencing system that works with a citation manager, but I can forgo that for now. I also hope to include a javascript library for image galleries, and for mermaid (a handy javascript-based chart generation tool)

Django Defense

Why did I pick Django? That decision-making process seems to have been glossed over, but for me one of the biggest selling points of Django is the vast trove of documentation, both official and around the web. For many of the problems I've been having, it seems someone has had that problem before, which gives me hope that the community is large enough to sustain a relatively robust community knowledge. Django has been around for so long that there are also verifiable experts on it who have made it their career, their textbooks, and I don't think that I would really get stuck because it's in Python.

But the real selling point was that about five years ago I walked through a relatively straightforward tutorial of how to build a library's website in Django from the Mozilla Developers Network website. I found this walkthrough detailed and helpful. It revealed how flexible Django was and yet how simple it was to build and maintain something quite complex. For me at the time, and still now, it revealed Django to be a good blend between expert tool and yet still a good fit for a novice. For someone who wants to be able to iterate quickly and simply, but if need be, get under the hood and mess around with things, I think this is a good balance. Let's see if I eat my words.