Post Heading
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
{ id: "build-static-website-generator-part-1" title: "Build A Static-Website Generator With Elixir, Part 1" blurb: "We take the first steps in designing and implementing the \"world's simplest static-website generator\". Building on tools and knowledge we acquired previously, and utilizing an incremental and iterative development process, we go through the entire software life-cycle from creating the initial project files to deploying to production. We spare nothing, from spelling out every command, to ensuring application integrity with tests, and even updating the README file. Grab a drink and some snacks, and dive right in!" } --- title: "Build A Static-Website Generator With Elixir, Part 1" blurb: "We take the first steps in designing and implementing the \"world's simplest static-website generator\". Building on tools and knowledge we acquired previously, and utilizing an incremental and iterative development process, we go through the entire software life-cycle from creating the initial project files to deploying to production. We spare nothing, from spelling out every command, to ensuring application integrity with tests, and even updating the README file. Grab a drink and some snacks, and dive right in!" ... ::: info This post was originally intended to be the first in a multi-part series. However, the deeper we got into this project, the more we realized we were basically implementing our own version of a web framework. Rather than continuing, we opted to change course and adopted an already-existing framework, [Phoenix](https://www.phoenixframework.org/), and simply added a Markdown-to-HTML conversion feature. As a consequence, there are no other parts to this post, but a description of the solution we chose instead can be found [here](/posts/publish-markdown-documents-as-static-web-pages-with-pandoc-and-phoenix). ::: This is one of our longer posts, so we've included a table of contents. ## Table of Contents - Introduction - Incremental Development Concepts - Iterative Development Concepts - Initial Planning - Deliverables - Initialization - Planning - Requirements - Analysis & Design - Implementation - Testing - Deployment - Evaluation - Project Control List - New Tasks - Completed Tasks - Conclusion ## Introduction We want to build the world's simplest static-website generator. Also, we want to use an iterative and incremental development method to do it. Finally, we want to use the Elixir programming language. Before we dive in, here's an extremely short primer on iterative and incremental development processes. We will combine these two ideas as we build this project. ### Incremental Development Concepts - The system is broken down into small pieces - Requirements are worked through in order of priority ### Iterative Development Concepts - The entire software development lifecycle is traversed in each iteration - Initialization, the initial "iteration", builds a base version of the system - All tasks and priorities are tracked in a Project Control List We are now in the initialization phase. We will go through each of the seven iteration steps to build a minimum base system. 1. Planning 2. Requirements 3. Analysis & Design 4. Implementation 5. Testing 6. Deployment 7. Evaluation ## Initial Planning ### Deliverables #### Functional Requirements * A way to publish written work online (ie blog) #### Non-Functional Requirements * Must use Elixir We love Elixir and functional programming. * Must be as simple as possible It's got to be dead simple. The app and the code. It's so easy to get carried away and over-engineer. Simplicity is a must-have requirement. * Must use an iterative and incremental development method In other words, short feedback loop/development life-cycle. Rather than releasing a minimum number of features as "version 1", we implement the smallest useful feature possible and release immediately. ## Initialization ### Planning We want to deliver the smallest increment of functionality possible, so we're going to start simple. We will first add an `index.html` serves as the initial page for our static website. Then, we will add a development server to serve the site to ourselves so we can see how it looks before we deploy it live. ### Requirements #### Functional 1. Post written text online This is the essence of the deliverable. Posting written text online is the first functionality we will deliver. #### Non-functional * A way to see what the output will look like locally before it is deployed This will make our lives easier during development and shorten the feedback loop. ### Analysis & Design #### Analysis The smallest bit of functionality we can offer is a static website with a single HTML file. We actually made a [proof of concept](https://github.com/webdevcat-me/docker_static_site_test) that does exactly this already and described the process in detail in an [earlier post](deploy-elixir-generated-html-with-docker-on-digitalocean.html). If we can add a development web server, that will pretty much meet all of our requirements. #### Design We could list our posts in a single HTML file, sorted in descending order of date, so that the most recent posts are at the top. Readers should have to scroll down to see older posts. Ideally, each post would have a title, a short message, and the date it was posted. The text should not stretch across the whole viewport on a wide screen, but should wrap at a point that facilitates readability. The markup should be [well-structured](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Document_and_website_structure) and valid. The column of text should be centered in the viewport but the text itself should be left-aligned. ##### Name We've chosen "Serval" for the project name. ### Implementation #### 1. Create a new Mix project We're going to need a supervisor to start our development server later when we add it, so we use the `--sup` option when we run the `mix new` command to generate our initial project files. We can refer to our [explanation of this command](/posts/deploy-elixir-generated-html-with-docker-on-digitalocean.html#create-the-mix-project) previously, if necessary. ``` $ docker run --rm -w /opt -v $PWD:/opt -u $(id -u):$(id -u) elixir mix new serval --sup ``` Then, we initialize Git in our project directory. ``` $ cd serval $ git init ``` Configure the user name and email, if necessary. ``` $ git config user.email "webdevcat@proton.me" $ git config user.name "Catalin Mititiuc" ``` Lastly, create the initial commit. ``` $ git add . $ git commit -m "Initial commit" ``` #### 2. Create a GitHub repo After creating the remote repo on GitHub, we add it as the origin and push up our initial commit. ``` $ git remote add origin git@github.com:webdevcat-me/serval.git $ git push -u origin master ``` #### 3. Add an `index.html` file to the root directory Just a simple HTML boilerplate, for now. ::: filename-for-code-block `index.html` ::: ```html
Lorem ipsum dolor sit amet, consectetur adipiscing elit.