Web development
Overview¶
This chapter on web development primarily covers HTML and CSS, which are the two structural languages for web development. Together they form the underlying structure and style of websites. It also covers React which is the biggest web framework, and introduces static site generation with Zola and Tera templates.
HTML¶
HyperText Markup Language or HTML is an XML based language for declaring the structure of a website. It looks like this.
<body>
<h1>Hello World!</h1>
<p class="my-subtitle">This is an introduction example for programming in HTML</p>
</body>HTML consists of elements which are surrounded by tags, have attributes and contain content. An element is a “thing” on the page like an article, button, header, text input, etc. in HTML we define an element by using an opening tag and a closing tag. In the above example, the <body> tag tells the computer that everything until </body> is part of the “body” element of the page (which is the displayed content). We also have a <h1> tag which represents a header element and a <p> tag which represents a paragraph element.
An attribute tells the computer something about the element. In our above example, for the paragraph element (<p class="my-subtitle">) we set the class attribute to “my-subtitle” which tells the computer that this paragraph should be styled using the my-subtitle styles (which we would define in CSS). There are many different attributes but id and class are some of the most common.
Lastly the content of an element is whatever is inside the element. In our example, the header element has “Hello World!” as its content. The body element has a header and a paragraph as it’s content (or called its children).
Let’s move on to a more complete example, one that you could open in your web browser. I’ve added comments explaining some of the structure.
<!DOCTYPE html> <!-- Required for Standard HTML -->
<html lang="en">
<head>
<!-- The <head> element contains the metadata for the page
things like the charset (encoding), page title (displayed
in the URL bar), styles, and maybe some scripts.
Nothing in the head is visible -->
<meta charset="utf-8">
<title>An introduction page</title>
<link rel="stylesheet" href="style.css">
<script src="script.js"></script>
</head>
<body>
<!-- The body element is the main displayed element.
This is where the main content of the website goes. -->
<h1>Hello World!</h1>
<p class="my-subtitle">This is a more complete example for programming in HTML</p>
<button id="click-me">Click me</button>
</body>
</html>Overall, HTML is a fairly simple language that lets you declare the structure of the page. It is also deeply integrated with CSS and JS which allows complex apps to be built with it.
CSS¶
Cascading Style Sheets or CSS is a styling language for HTML. It specifies how the page should look.
/* Anything in this block is applied to h1 elements */
h1 {
font-size: 20pt;
font-weight: bold;
}
/* This will apply to any p element. */
p {
margin-top: 5px;
margin-bottom: 5px;
}
/* .my-subtitle will apply to any element with class="my-subtitle". */
.my-subtitle {
margin-top: 2px;
font-size: 16pt;
color: gray;
}
In this example, we style our header and our paragraph. Also note that multiple style blocks can apply to a single element. If two blocks contain the same style (like ‘margin-top’) the most “specific” style wins. In general, this means that a style in a class block beats a style in an element block. So for our <p class="my-subtitle">, the .my-subtitle styles will take preference over the p styles. In this case the only conflicting style is margin-top and so margin-top: 2px wins.
JS and the DOM¶
JavaScript can interact with the HTML using the Document Object Model or the DOM. This is just a (large) set of functions that are used to interact with HTML elements from JavaScript. We can show a simple example with our button.
// This gets a reference to the HTML element
let myBtn = document.getElementById("click-me");
// This tells the browser to run a function when the button is clicked
myBtn.addEventListener("click", () => {
alert("You clicked me!");
});Now when you click the button, you will get an alert saying “You clicked me!” This is one of the most basic examples, but there are many functions for listening to events, getting input, adding/removing elements, etc.
Reactth¶
React is the most popular frontend framework. A framework is a tool or library that makes writing HTML and JavaScript easier or more organized. One of the main issues with HTML is that you can only have one HTML file for one page on a website. This does not scale well to large apps, so you either need to create your elements with JS (annoying and bug prone) or write a very large HTML file (also annoying).
React attempts to solve this problem by allowing you to write HTML code within JS. It also introduces the idea of components which are custom reusable elements that you can use similarly to existing HTML elements.
Here’s a basic example.
// This is a reusable component
function MyButton() {
// React has a nice way to handle "state" using this function
// It allows you to update state in JS and have it auto update the HTML
let [count, setCount] = useState(0);
return (
{/* we can use JS variables in our HTML */}
<button onclick={() => setCount(count + 1)}> Counter: {count} </button>
)
}
// Here we define a component for the main content
function App() {
return (
<>
<h1>Hello World!</h1>
<p class="my-subtitle">This is a more complete example for programming in HTML</p>
{/* Here is our custom component */}
<MyButton />
</>
)
}
This creates a website with a counter that updates every time the button is clicked. This shows most of the main features of React.
One thing to note is that these component functions (MyButton() and App()) can be run by React multiple times which mean they should not have “side effects” which means they shouldn’t update global state or make web requests or anything like that.
// This is a reusable component
function MyButton() {
let [count, setCount] = useState(0);
// This is could be run any number of times!
console.log("MyButton() was called");
return (
<button onclick={() => setCount(count + 1)}> Counter: {count} </button>
)
}In the above example could output “MyButton() was called” any number of times. In practice, it will likely only update every time the state changes because React needs to update the button text, but that is not guaranteed. If you need to run something once or only when a variable changes you can use useEffect like below.
function MyButton() {
let [count, setCount] = useState(0);
useEffect(() => {
console.log("This will only run once when the component is created");
}, []); // <-- note the empty array
useEffect(() => {
console.log("Count changed. New count: " + count);
}, [count]); // <-- note the "count" in the array
return (
<button onclick={() => setCount(count + 1)}> Counter: {count} </button>
)
}Many modern large scale web apps are built with these basic building blocks. Since they are reusable, they can greatly reduce the complexity of codebases.
Zola¶
Static site generators¶
A static site generator builds web pages from content files and reusable templates. Instead of writing a complete HTML document for every page, authors write content in Markdown and define the layout separately. The generator combines these into HTML files that a web server can deliver to visitors.
This approach works well for documentation, blogs, and project websites. Pages are generated ahead of time, so the server does not need to build them for each request. A static website can still use JavaScript for interactive features.
How Zola fits together¶
Project Elara’s website uses Zola. Its projects separate the main parts of a website into directories:
content/holds Markdown pages.templates/holds reusable layouts written using Tera.static/holds files such as images that are copied into the generated site.sass/optionally holds stylesheets that Zola compiles into CSS.
The site configuration controls settings such as the website’s base URL and title. When Zola builds the site, it writes the generated files to public/ by default. The Handbook itself uses Jupyter Book; the Zola commands below apply to a Zola website project.
Basic commands¶
After installing Zola, these commands cover the usual workflow:
| Command | Purpose |
|---|---|
zola init my-site | Create a new project in my-site. |
zola serve | Build a local preview and rebuild when files change. |
zola build | Generate the website files for publishing. |
zola check | Check the site without writing output, including external links in Markdown. |
Run serve, build, and check from the project directory. After zola serve, open the address printed in the terminal, usually http://127.0.0.1:1111. This address is available only while the preview server is running. Press Ctrl+C to stop it.
For an existing project such as Elara’s website, follow its README for setup and the required Zola version. Use init when creating a new site. More options are described in the command documentation.
Templates with Tera¶
Zola uses Tera to combine HTML layouts with content. Tera expressions such as {{ page.title }} insert values, while statements inside {% ... %} control the template’s structure. These are processed during the build.
To try a small example, run zola init my-site, accept the setup defaults, and then run cd my-site. Add the following three files. The example creates a page at /hello/.
First, create content/hello.md:
+++
title = "Hello, Elara!"
template = "page.html"
+++
This is a first page built with Zola.The block between +++ markers is front matter, written here in TOML. It provides metadata, including the page title and which template to use. The Markdown below it supplies the page’s content.
A shared layout in templates/base.html defines the HTML structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{% block title %}Example site{% endblock title %}</title>
</head>
<body>
<main>{% block content %}{% endblock content %}</main>
</body>
</html>The page template, templates/page.html, reuses that layout:
{% extends "base.html" %}
{% block title %}{{ page.title }}{% endblock title %}
{% block content %}
<h1>{{ page.title }}</h1>
{{ page.content | safe }}
{% endblock content %}extends selects the shared layout, and the named blocks replace parts of it. This is called template inheritance: several pages can share the same structure without repeating it.
page.content contains the HTML generated from Markdown. The safe filter lets that HTML render as page content instead of displaying its tags as text. Use it only for HTML that is trusted.
Run zola serve and visit http://127.0.0.1:1111/hello/ to see the title and paragraph. This example defines a content page; it does not provide a custom homepage template.
Tera also supports conditions with {% if ... %} and repetition with {% for ... %}, useful for optional descriptions and lists of pages. See Zola’s template guide and the Tera documentation for further examples.