![\"Screenshot](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/5de790e7-56e8-4116-9bda-0ea66bdccb30.png\")
When trying to find a way to create a navbar, you will notice that there is no semantic way to make one with good UX in both mobile and desktop. The reason is simple, we want an element that is collapsed in mobile and expanded in desktop. Like what you see in my website. Because that’s what we usually see on most websites.
\nThe implementation for responsive navbars are usually one of the following — ordered by the number of times I see it on the internet
\nI notice this the most, and to be frank, it’s usually more accessible than most people think due because most use of aria-expanded attribute and role property.
\nThe cons are following:
\nI don’t mean it in just in file size, the page often takes a long-time load, especially when I am on mobile data. The types of sites that does this are typically restaurants and grocery websites.
\nIt is buggy more often than not when resizing the window. I resize webpages a lot since I use a tiling window manager on my laptop.
\nWhen on mobile, it is buggy, probably because the JavaScript takes a long time to load/run. I almost always need to wait a few seconds before it even notice that I tapped on something.
\nAt least I learnt some patients this way because I know better to not tap on again just because it’s not doing anything.
\nThis one is a simple hack, and it works well, but it’s usually not accessible.
\nThe idea is to create a label with an icon (typically hamburger menu), and hide the checkbox.\nThe checkbox can toggle if you press on the label, and CSS is used to style the sibling element when the checkbox is toggled.
\nThe styling is done in many ways, the best way I know is to position the navbar off-screen and move it into the view when the checkbox is toggled.
\nFrom the link, this is the first example and it works well.
\nnav {\n position: absolute;\n top: 0;\n left: -300px; /* width of the menu */\n width: 300px;\n height: 100vh;\n transition: 0.3s;\n}\n\n#menuToggle:checked + label + nav {\n left: 0;\n}\nMoving the navbar on and off-screen is better than hiding it because screen readers can still navigate into the navbar without toggling anything.
\nThe only con I can think of is:
\nThis is for multiple reasons.
\nMenulabel.
aria-expanded.HTML has plenty of interactive elements, like dialog, select elements, and popover attribute.
The details tag is one of the oldest one that works is most browsers.
\nFor example, this snippet produces an interactive disclosure element.
\n<details>\n<summary>Spoiler</summary>\nThis is a pure HTML interactive element.\n</details>\n<details name=\"accordion-menu\">\n<summary>First interactive menu</summary>\nThis is another pure HTML interactive element.\n</details>\n\n<details name=\"accordion-menu\">\n<summary>Second interactive menu</summary>\nThis is yet another pure HTML interactive element.\n</details>\nWith a bit of CSS, you can make it a menu that can overlay elements below it like a typical menu.
\n/*\n* I will be using this website's styles instead of this style my demo because,\n* I want it to work in all themes I have, but this CSS will give you a working menu.\n* You should be able to make it pretty~\n*/\n\n.navbar-nav {\n display: flex;\n align-items: center;\n gap: 1rem;\n list-style: none;\n margin: 0;\n padding: 0;\n flex-wrap: wrap;\n}\n\n.nav-dropdown {\n position: relative;\n}\n\n.nav-dropdown summary {\n list-style: none;\n cursor: pointer;\n user-select: none;\n display: flex;\n align-items: center;\n gap: 1rem;\n}\n\n.nav-link:hover {\n background-color: #23F;\n color: #FF2;\n}\n\n.nav-dropdown .dropdown-menu {\n list-style: none;\n}\n\n.dropdown-menu {\n position: absolute;\n top: 100%;\n left: 0;\n min-width: 220px;\n background-color: #fff;\n border: 2px solid #555;\n border-radius: 10px;\n padding: 1rem;\n margin-top: 0;\n z-index: 1000;\n}\n<nav class=\"navbar-nav\">\n<details class=\"nav-dropdown\" name=\"interactive-menu\">\n <summary class=\"nav-link\">Menu 1</summary>\n <ul class=\"dropdown-menu\" role=\"menu\">\n <li>Menu Item 1</li>\n <li>Menu Item 2</li>\n </ul>\n</details>\n<details class=\"nav-dropdown\" name=\"interactive-menu\">\n <summary class=\"nav-link\">Menu 2</summary>\n <ul class=\"dropdown-menu\" role=\"menu\">\n <li>Menu Item 1</li>\n <li>Menu Item 2</li>\n </ul>\n</details>\n</nav>\nCool, huh? Now For mobile, we can just wrap the nav inside another details tag because HTML allows it:
<details class=\"nav-dropdown\">\n<summary class=\"nav-link\">Mobile Menu</summary>\n<nav class=\"navbar-nav mobile-nav\">\n<details class=\"nav-dropdown\" name=\"interactive-menu\">\n <summary class=\"nav-link\">Menu 1</summary>\n <ul class=\"dropdown-menu\" role=\"menu\">\n <li>Menu Item 1</li>\n <li>Menu Item 2</li>\n </ul>\n</details>\n<details class=\"nav-dropdown\" name=\"interactive-menu\">\n <summary class=\"nav-link\">Menu 2</summary>\n <ul class=\"dropdown-menu\" role=\"menu\">\n <li>Menu Item 1</li>\n <li>Menu Item 2</li>\n </ul>\n</details>\n</nav>\n</details>\nIf you are not on a Mobile device, Resize this browser window or open this page in a mobile to see what the mobile menu will look like.
\nYou will notice that the menu stays open even if you click outside, that’s because the details tag doesn’t handle clicks outside it.
\nThe Navigation will be confusing for most users who are used to click outside or press the Esc key to close the menu.
\nOne way to not have this issue would be to not use details tag, and instead use popover or the dialog element I mentioned before. But they do not work in most browsers presently used (at the time of writing) because people don’t always update their browsers. So I am fine with that inconvenience. Just click the menu again to dismiss.
We can handle the clicks with JavaScript.
\nwindow.addEventListener(\"click\", function (event) {\n // if clicks are not on the menu button itself\n if (!event.target.closest(\".nav-dropdown\")) {\n // Hide all the menu if open.\n Array.from(document.querySelectorAll('.nav-dropdown[open]')).forEach(\nmenu=>menu.removeAttribute(\"open\"))\n }\n});\nThat will work, but JavaScript is disabled on this site, so you can’t test it here.
\nTo switch between desktop and mobile navigation, if you have many items in the navbar, it is common practice to make the navbar itself a menu. Unfortunately, there is no way to show the contents of a detail tag when it is closed using any means. So the best possible way would be to create two navbars and show/hide them using media queries.
\nYou may ask why the duplication of navbar is an accessibility issue when we can hide it. Well, the eye candy CSS can be disabled for people who don’t need it. There can be network issues, or some plugin might have blocked it. Or your CSS file might be corrupted, or visitors might be using a text-only browser, the list goes on.
\nThis section was added on 2026-01-20
\nOne way to tackle hiding an element in all browsers is by using the hidden global attribute. It can be overwritten easily using CSS by styling it with display CSS property with any value besides none (i.e display:block will show the element regardless of its hidden HTML attribute).
Chris Coyier wrote on CSS tricks that The
. But it is one of the best ways to optionally element when the browser does not load CSS or JavaScript.hidden Attribute is Visibly Weak
Unfortunately, even the feature-rich text-based browsers I tried does not treat the hidden attribute as a global one. If you are one of the developers who work on such browsers, please add support for it.
The best JS-free, responsive, semantic, and accessible navbar is to not have a navbar. Yes, you read that correctly.
\nInstead of a navbar, there are two ways I can think of:
\nA navblock is a list of links on the top (header), or bottom (footer), of the page. I have seen many government websites doing this. It’s mostly because they have too many pages and not everything can be listed without overwhelming the visitor. Instead, show all relevant links somewhere on the page.
\nFor small blogs and indie sites, it might be better to just write a small paragraph with the things you do and add links to them. For example, in the home page I wrote the following:
\n\n\nThis is my personal website containing my blogs, projects, stories, other things I do, and ways to contact me. It partially supports the IndieWeb while keeping accessibility, minimalism, and your privacy in mind.
\n
Adding this in every page will accomplish two things:
\nI am sure you have better ideas, let me know it in using webmention below, or just send an email :)
\n","content_text":"When trying to find a way to create a navbar, you will notice that there is no semantic way to make one with good UX in both mobile and desktop. The reason is simple, we want an element that is collapsed in mobile and expanded in desktop. Like what you see in my website. Because that's what we usually see on most websites.\r\n\r\nThe implementation for responsive navbars are usually one of the following — ordered by the number of times I see it on the internet\r\n\r\n## div-soup with a front-end JavaScript framework\r\n\r\nI notice this the most, and to be frank, it's usually more accessible than most people think due because most use of [aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute and [role](https://developer.mozilla.org/en-US/docs/Web/API/Element/role) property.\r\n\r\nThe cons are following:\r\n\r\n### Bloat\r\n\r\nI don't mean it in just in file size, the page often takes a long-time load, especially when I am on mobile data. The types of sites that does this are typically restaurants and grocery websites.\r\n\r\n### Buggy\r\n\r\nIt is buggy more often than not when resizing the window. I resize webpages a lot since I use a tiling window manager on my laptop.\r\n\r\nWhen on mobile, it is buggy, probably because the JavaScript takes a long time to load/run. I almost always need to wait a few seconds before it even notice that I tapped on something.\r\n\r\nAt least I learnt some patients this way because I know better to not tap on again just because it's not doing anything.\r\n\r\n## Hidden Checkbox Hack\r\n\r\nThis one is a simple hack, [and it works well](https://dev.to/joxx/toggling-mobile-navigation-visibility-with-css-the-checkbox-hack-7ej), but it's usually not accessible.\r\n\r\nThe idea is to create a label with an icon (typically hamburger menu), and hide the checkbox.\r\nThe checkbox can toggle if you press on the label, and CSS is used to style the sibling element when the checkbox is toggled. \r\n\r\nThe styling is done in many ways, the best way I know is to position the navbar off-screen and move it into the view when the checkbox is toggled.\r\n\r\nFrom the link, this is the first example and it works well.\r\n\r\n```css\r\nnav {\r\n position: absolute;\r\n top: 0;\r\n left: -300px; /* width of the menu */\r\n width: 300px;\r\n height: 100vh;\r\n transition: 0.3s;\r\n}\r\n\r\n#menuToggle:checked + label + nav {\r\n left: 0;\r\n}\r\n```\r\n\r\nMoving the navbar on and off-screen is better than hiding it because screen readers can still navigate into the navbar without toggling anything.\r\n\r\nThe only con I can think of is:\r\n\r\n### It's not Accessible\r\n\r\nThis is for multiple reasons.\r\n\r\n1. The Label would be just a CSS with three lines that does not describe what it is, i.e, an empty label, so it's confusing to navigate into with assistive tech. Devs with more knowledge are now adding [visually hidden text](https://www.w3.org/WAI/WCAG21/Techniques/css/C7) or [CSS alt texts for content](https://developer.mozilla.org/en-US/docs/Web/CSS/content), or just adding a visibleMenulabel. \r\n2. Even if the checkbox is labelled, it wouldn't announce that something has changed in the screen because CSS cannot set `aria-expanded`.\r\n3. Not everyone can tap on small buttons on the top corner, even the able personals.\r\n\r\n## Semantic Details Tag\r\n\r\n`HTML` has plenty of interactive elements, like [dialog](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog), [select](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select) elements, and [popover](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute.\r\n\r\nThe [details](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) tag is one of the oldest one that works is most browsers.\r\n\r\nFor example, this snippet produces an interactive disclosure element.\r\n\r\n```html\r\n
[The `hidden` Attribute is Visibly Weak ](https://css-tricks.com/the-hidden-attribute-is-visibly-weak/). But it is one of the best ways to optionally element when the browser does not load CSS or JavaScript.\r\n\r\nUnfortunately, even the feature-rich text-based browsers I tried does not treat the `hidden` attribute as a global one. If you are one of the developers who work on such browsers, please add support for it.\r\n\r\n## The Best Navbar\r\n\r\nThe best JS-free, responsive, semantic, and accessible navbar is to not have a navbar. Yes, you read that correctly.\r\n\r\nInstead of a navbar, there are two ways I can think of:\r\n\r\n### Make it a Navblock\r\nA navblock is a list of links on the top (header), or bottom (footer), of the page. I have seen many government websites doing this. It's mostly because they have too many pages and not everything can be listed without overwhelming the visitor. Instead, show all relevant links somewhere on the page.\r\n\r\n### Write a sentence\r\nFor small blogs and indie sites, it might be better to just write a small paragraph with the things you do and add links to them. For example, in the home page I wrote the following:\r\n\r\n> This is my personal website containing my [blogs](/blogs), [projects](/projects), [stories](/stories), other things I do, and [ways to contact me](/contact-me). It [partially supports](/am-i-indieweb-yet) the [IndieWeb](https://indieweb.org/) while keeping accessibility, minimalism, and your privacy in mind.\r\n\r\nAdding this in every page will accomplish two things:\r\n1. Some description about the author will be present in every page.\r\n2. Avoid navbar and free up some screen space.\r\n\r\nI am sure you have better ideas, let me know it in using webmention below, or just send an email :)","summary":"Once you get into web development, you will eventually start to attempt accessible development. And once you see the state of web, you will also want to create a website without JS and with less bloat.Then you hit a brick wall, it's called a navbar.","date_published":"2025-10-27T13:41:53Z","date_modified":"2026-01-20T20:16:57Z","authors":[{"name":"Coding Otaku","url":"https://codingotaku.com/users/otaku"}]},{"id":"https://codingotaku.com/blogs/adding-indieauth","url":"https://codingotaku.com/blogs/adding-indieauth","title":"Adding IndieAuth to My Website","content_html":"
Note: Most code examples in this page are in Rust and in the Handlebars template. But that shouldn’t be a problem to follow this, the base logic remains the same, regardless of what language you use, the Rust just helps me avoid a few unnecessary checks.
\nIn my last post, I wrote about adding Webmentions to this website. It ended with me saying that I will add IndieAuth support next. But as I was busy being laid off and searching for a job (I’m still searching for one), I couldn’t really find much time to do it. But I also wanted a new blog post to come out at every month, so here I am trying to keep my promise.
\nThe first step is to read the IndieAuth specification. I will ignore the client-side parts in this blog post, as they are irrelevant to me.
\nWhat I am going to do is a single-user authentication. Since I am not allowing others to login through my website, the process is even simpler. It should be possible to change this implementation to handle multi-user authentication without much effort.
\nFor us to login to other IndieWeb webistes/apps (clients), we need an authorization endpoint, and to allow publishing through a client, we need a token endpoint.
\nCurrently, I publish all posts on my website as HTML files in handlebars template format. Due to this, token endpoint does not make sense for me to implement right now, but I am updating this website more regularly now, so it might be a thing I do in the future!
\nAuthentication is the act of validating that users are whom they claim to be. The IndieAuth specification tells us how this works, let us note it down first.
\nThe endpoint that handles the request is an authorization endpoint instead of an authentication endpoint. This is because both authentication and authorization go through the same route at the beginning.
\nIn the following list, the client would be a website or app that I am logging on to, like indieweb.org.
\nrel=authorization_endpoint value.You can see that half of the steps are done from the client side, so it is not as complex as it looks.
\nThe authorization code we need to generate could be anything, the specification has not mandated a format or length, so I am thinking of just using a UUID for this.
Now I know what needs to be done, and where to look for the specification, so it’s time to do some coding.
\nI have an existing login implementation, this is a username and password-based authentication and I use it for moderating webmentions (previously comments). The password is hashed and salted. Once logged in, I store the login status in a private cookie.
\nTo support the authorization confirmation screen that I will develop later, I need to modify the login page to redirect to a URL path when present, so I will start with that.
First, I will accept a new optional string parameter named redirect_path in the login request parameter, I will use this to redirect to the authorization endpoint.
#[get(\"/login-to-site?<redirect_path>\")]\nasync fn login_page(redirect_path: Option<&str>, ... ) -> Template {\n ...\n Template::render(\"admin/login-to-site\",\n ...\n page {\n ...\n redirect_path\n ...\n }\n ...\n )\n ...\n}\nI used the redirect_path in my template as a hidden input element. Maybe I should inform myself about this redirection, but I don’t think that will be a problem as there are more manual steps to be done afterwords and I also do security checks later.
{{#if page.redirect_path}}\n <input type=\"hidden\" name=\"redirect_path\" value={{page.redirect_path}}>\n{{/if}}\nIf you are interested, you can see these changes in my commit history.
\nI now need to redirect to this URL when the login POST request is successful, but I do not want to redirect to any page that comes up in the URL. I need all redirections to be within my website domain. This is as simple as making sure that the path starts with a forward slash (/). So I wrote a helper method to handle all in-page redirections.
fn redirect_to_path(mut optional_path: Option<String>, default: String) -> Redirect {\n let path = optional_path.take_if(|path| path.starts_with(\"/\"));\n Redirect::to(path.unwrap_or(default))\n}\nThe idea is to make the login page redirect back to the authorization page, and do a final confirmation within the authorization page that will do the authentication response.
\nThis is the page we would land on after trying to sign in through a client using my domain URL. I want this to be as simple as possible, and I am also thinking of adding the token endpoint support to it later.
\nAnyway, I went back and read the specification again to get an example of what we will get from the client, and it is a GET request like this:
https://example.org/auth?me=https://user.example.net/&\n redirect_uri=https://app.example.com/redirect&\n client_id=https://app.example.com/&\n state=1234567890&\n response_type=id\nLooking at the specification, I know the following:
\nme should be my domain URL in its canonical form (e.g. https://codingotaku.com/).redirect_uri is the URI I need to redirect to after authorization.client_id is the URI of the app.state is a value that I need to send to the client as it is to avoid cross-site request forgery.response_type that defaults to id means that this is an authentication request.If the response_type is code, that means that it is an authorization request instead of an authentication request, we will handle this later, for now, I will treat all requests as an authentication request.
Ideally, the redirect_uri would be using the same host and port as the client_id. But this might not be the case always. So we need to ensure that the client supports the redirect_uri provided by crawling the client. But I decided to just accept those requests in the initial version, and add that in after finding a good HTML parsing library for rust.
As the specification tells, it is important to show as much detail as possible in authorization page. My idea is to display the response_type, client_id, and the redirect_uri on the page. So that I can do a manual verification before logging in. This way, I can catch the abnormalities, like client_id and redirect_uri not matching.
The page code will look something like this (written in handlebars template):
\n<p>You are receiving a request to authenticate to <a href=\"{{page.client_id}}\">{{page.client_id}}</a></p>\n<p>After authentication, this page will be redirected to <code>{{page.redirect_uri}}</code></p>\n<p>If this request looks suspicious, please manually verify them, or avoid authenticating the request.</p>\n\n<h2>Request details</h2>\n<dl>\n <dt><strong>Client ID</strong></dt>\n <dd>{{page.client_id}}</dd>\n <dt><strong>Redirect URI</strong></dt>\n <dd>{{page.redirect_uri}}</dd>\n <dt><strong>Response type</strong></dt>\n <dd>{{page.response_type}}</dd>\n</dl>\nThe authentication page needs to check whether I am logged in or not, and If I am logged in, a button should be shown to do the authentication; otherwise, I should be asked to log in.
\n{{#if settings.is_logged_in}}\n<form class=\"form\" action=\"/authentication\" method=\"post\" accept-charset=\"utf-8\" aria-label=\"Authentication\">\n <input type=\"hidden\" name=\"redirect_uri\" value={{page.redirect_uri}}>\n <input type=\"hidden\" name=\"response_type\" value={{page.response_type}}>\n <input type=\"hidden\" name=\"state\" value={{page.state}}>\n <input type=\"hidden\" name=\"client_id\" value={{page.client_id}}>\n <input type=\"hidden\" name=\"me\" value={{page.me}}>\n <button type=\"submit\" class=\"submit-button\">Authenticate</button>\n</form>\n{{else}}\n <p class=\"space-out\"><a class=\"link-button\" href=\"/login-to-site?redirect_path={{page.escaped_uri}}\">Login to Authenticate this request</a></p>\n{{/if}}\nHere is a screenshot of the authentication page before logging in:
\nAfter logging in, the only change is that I replaced the login link with a button to authenticate the request, here is the screenshot:
\n![\"Screenshot](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/53477476-6bd6-40be-bc74-c5f239a3b17e.png\")
The complete page template can be found in my repository.
\nTo keep track of the authentication requests, I will create a new table named indie_auth_code. Within this, I will add all six columns that I will be needing for authentication.
id: for me to query them later.client_id: The client requesting for authentication.redirect_uri: The redirect URI send by the client.code: a unique authentication/authorization code.created_on: The date and time of creating this row.expire_on: the date and time when the code expires.I use SQLite for storing things on my website, and the table schema looks like this:
\nCREATE TABLE indie_auth_code (\n id TEXT NOT NULL,\n client_id TEXT NOT NULL,\n redirect_uri TEXT NOT NULL,\n code TEXT NOT NULL,\n created_on DATETIME NOT NULL,\n expires_on DATETIME NOT NULL,\n UNIQUE(code)\n);\nNow that we have a table, we reached the main part of the whole process. It is time to do the actual authentication.
\nI created a new endpoint named authentication. This receives a POST request that contains all values that will be sent by the client. The response will always be a redirection.
#[derive(FromForm)]\npub(crate) struct IndieAuthForm {\n pub me: String,\n pub client_id: String,\n pub redirect_uri: String,\n pub state: String,\n pub response_type: Option<String>,\n}\n\n#[post(\"/authentication\", data = \"<indie_auth>\")]\nasync fn authentication(indie_auth: Form<IndieAuthForm>) -> Redirect {\n ...\n}\nYou will notice that reponse_type is an Option, this is because it is an optional parameter that defaults to the string \"id\".
The authentication endpoint will first ensure that both the client_id and rediect_uri are of the same host and port. I wrote a few helper methods for this:
fn is_port_matching(source: Option<u16>, target: Option<u16>) -> bool {\n (source.is_none() && target.is_none())\n || (source.is_some_and(|_| target.is_some()) && source.unwrap().eq(&target.unwrap()))\n}\n\nfn is_host_matching(source: &str, target: &str) -> bool {\n !(source.is_empty() || target.is_empty() || source.ne(target))\n}\n\nfn get_url_authority(uri_value: &str) -> Option<Authority> {\n let url = uri::Absolute::parse(uri_value);\n\n url.map_or(None, |url| url.authority().cloned())\n}\n\nfn is_authority_matching(source_uri: &str, target_uri: &str) -> bool {\n let source = get_url_authority(source_uri);\n let target = get_url_authority(target_uri);\n\n source.is_some_and(|source_val| {\n target.is_some_and(|target_val| {\n is_host_matching(source_val.host(), target_val.host())\n && is_port_matching(source_val.port(), target_val.port())\n })\n })\n}\nThe helper methods will handle all edge cases of varying ports and host names, but if they differ, I will need to crawl the client to find the redirect_uri. As I mentioned before, I do this manually now. I’ll update this blog once I find time to do a proper check.
\nOnce the first check was done, I generated a new UUID, and stored it in the indie_auth_code table we created before. We already have all the details we need, the created_on is the current time and expires_on will be around 5 minutes past the current time.
let code = Uuid::new_v4().to_string();\nlet now = OffsetDateTime::now_utc();\n\nlet auth_code = IndieAuthCode {\n id: Uuid::new_v4().to_string(),\n client_id: indie_auth.client_id.clone(),\n redirect_uri: indie_auth.redirect_uri.clone(),\n code: code.clone(),\n created_on: now.format(&well_known::Iso8601::DEFAULT).unwrap(),\n expires_on: now\n .checked_add(Duration::minutes(5))\n .unwrap()\n .format(&well_known::Iso8601::DEFAULT)\n .unwrap(),\n};\n\nadd_auth_code(&mut db, &auth_code).await;\nThe specification suggests a maximum of 10 minutes for the expiration time, but let us play a little safe and keep it at 5. I want it to change the time limit via a config or something in the future.
\nOn hindsight, setting time is something I could do from the database itself, but this is what we are going with right now.
\nI sent it to redirect_uri along with the given state as an HTTP redirect with 302 Found status.
You can find the full implementation with more error handling in my repository.
\nEverything is coming together, now as per the specification, I need to accept another Authorization Code Verification request being sent by the client to the authorization endpoint.
\nThe validation part is simple, the client will give us the code, client_id, and the redirect_uri as the POST parameter. We just need to return the profile URL as a JSON to the client after the validating it against the details we saved in the last step within the indie_auth_code table. My response will need to look like this:
{\n \"me\": \"https://codingotaku.com/\"\n}\nIn case of errors, I am just sending the error code instead, something like this:
\n{\n \"error\": \"invald_request\"\n}\nAll validations can be done from the database itself, so I wrote this query:
\nSELECT id, client_id, redirect_uri, code, created_on, expires_on, is_accessed\n FROM indie_auth_code\n WHERE code=[the-received-cde]\n AND client_id=[received-client-id]\n AND redirect_uri=[received-redirect-uri]\n AND datetime(expires_on) > datetime('now');\nThe query is being used by my authorization endpoint, I also do the redundant checks to ensure that the request is valid before doing the query, this is not really needed, but it can prevent an unnecessary query.
#[post(\"/indie-auth\", data = \"<code_verification>\")]\nasync fn auth_verification(\n mut db: Connection<Db>,\n code_verification: Form<IndieAuthCodeVerification>,\n config: &State<AppConfig>,\n) -> (Status, Json<IndieAuthResponse>) {\n if !is_authority_matching(\n &code_verification.client_id,\n &code_verification.redirect_uri,\n ) {\n return (\n Status::BadRequest,\n Json(IndieAuthResponse {\n me: None,\n error: Some(String::from(\"invalid_request\")),\n }),\n );\n }\n\n if let Ok(auth_code) = get_auth_code(&mut db, &code_verification).await {\n delete_auth_code(&mut db, &auth_code.id).await;\n (\n Status::Found,\n Json(IndieAuthResponse {\n me: format!(\"{}/\", config.card.homepage).into(),\n error: None,\n }),\n )\n } else {\n (\n Status::NotFound,\n Json(IndieAuthResponse {\n me: None,\n error: Some(String::from(\"invalid_grant\")),\n }),\n )\n }\n}\nThe final step is to actually use this endpoint. Until now, I was using indieauth.com/auth as the endpoint, I updated it to the new codingotaku.com/indie-auth.
Note: If you go to that page without proper request parameters, I will just show you a 404 not found page, this is to trick some of the bad bots that I’ve been getting.
\nIf you would like to see the complete set of changes, here is the commit difference between the implementations (you’ll need to scroll down a bit to see the files).
\nMy initial approach was to reject the authentication request if the response_type is not “id” or empty. But all the clients I tried to log in sent me the response_type as “code” instead. Annoyingly, it is also true for the indieweb.org. It could either be a bug, or they have more features that I can unlock once I add a token endpoint.
In my current implementation, I am just printing this on to the console and ignoring it (I know, shut up). But I will need to handle this by creating a token endpoint later.
\nOther than this one thing, I haven’t really faced any other issues, hope this helps, now I am having 100% IndieWeb implementation done by myself without depending on a service!
\nAs I have mentioned a few times in the article, I am still missing a token endpoint. But I have some work already being done on a separate branch to use a database for all the posts. It is a big task as I need to think of better backup systems in case I corrupt the DB.
\nOnce the database work is done, I will be able to add a token endpoint and post without updating the repository all the time 😄.
\n","content_text":"**Note:** Most code examples in this page are in [Rust](https://www.rust-lang.org/) and in the [Handlebars template](https://handlebarsjs.com/). But that shouldn't be a problem to follow this, the base logic remains the same, regardless of what language you use, the Rust just helps me avoid a few unnecessary checks.\n\nIn my [last post](/blogs/adding-webmentions), I wrote about adding [Webmentions](https://www.w3.org/TR/2017/REC-Webmention-20170112/) to this website. It ended with me saying that I will add [IndieAuth](https://www.w3.org/TR/indieauth) support next. But as I was busy being laid off and searching for a job (I'm still searching for one), I couldn't really find much time to do it. But I also wanted a new blog post to come out at every month, so here I am trying to keep my promise.\n\n## The basics\n\nThe first step is to read the [IndieAuth specification](https://www.w3.org/TR/indieauth/). I will ignore the client-side parts in this blog post, as they are irrelevant to me.\n\nWhat I am going to do is a **single-user authentication**. Since I am not allowing others to login through my website, the process is even simpler. It should be possible to change this implementation to handle multi-user authentication without much effort.\n\nFor us to login to other IndieWeb webistes/apps (clients), we need an [authorization endpoint](https://www.w3.org/TR/indieauth/#authorization-endpoint), and to allow publishing through a client, we need a [token endpoint](https://www.w3.org/TR/indieauth/#token-endpoint).\n\nCurrently, I publish all posts on my website as [HTML files](https://codeberg.org/codingotaku/website/src/branch/main/templates) in handlebars template format. Due to this, **token endpoint** does not make sense for me to implement right now, but I am updating this website more regularly now, so it might be a thing I do in the future!\n\n## Authentication\n\nAuthentication is the act of validating that users are whom they claim to be. The IndieAuth specification [tells us how this works](https://www.w3.org/TR/indieauth/#x5-authentication), let us note it down first.\n\nThe endpoint that handles the request is an **authorization endpoint** instead of an **authentication endpoint**. This is because both authentication and authorization go through the same route at the beginning.\n\nIn the following list, the client would be a website or app that I am logging on to, like [indieweb.org](https://indieweb.org).\n\n1. I enter my [profile URL](https://www.w3.org/TR/indieauth/#user-profile-url) in the login form of the client and click \"Sign in\"\n2. The client discovers my **authorization endpoint** by fetching my **profile URL** and looking for the `rel=authorization_endpoint` value.\n3. The client builds the [authentication request](https://www.w3.org/TR/indieauth/#authentication-request) including its [client identifier](https://www.w3.org/TR/indieauth/#client-identifier), **local state** (a random string), and a [redirect URI](https://www.w3.org/TR/indieauth/#redirect-url), and redirects the browser to the **authorization endpoint** I am creating now.\n4. The **authorization endpoint** fetches the client information from the client identifier URL to have an application name and icon to display to me. (I might will this and just show the URLs to avoid complexity)\n5. The **authorization endpoint** prompts me to log in and asks whether to grant or deny the client's authentication request.\n6. The **authorization endpoint** generates an **authorization code** and redirects the browser back to the client, including the **local state** in the URL. This is called an [authentication response](https://www.w3.org/TR/indieauth/#authentication-response).\n7. The client [verifies the authorization code](https://www.w3.org/TR/indieauth/#authorization-code-verification) by making a POST request to the authorization endpoint. The authorization endpoint validates the authorization code, and [responds](https://www.w3.org/TR/indieauth/#response) with the End-User's canonical profile URL.\n\nYou can see that half of the steps are done from the client side, so it is not as complex as it looks.\n\nThe `authorization code` we need to generate could be anything, the specification has not mandated a format or length, so I am thinking of just using a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) for this.\n\n### Implementing Authentication\n\nNow I know what needs to be done, and where to look for the specification, so it's time to do some coding.\n\n#### Updating the existing login\n\nI have an [existing login implementation](https://codeberg.org/codingotaku/website/src/commit/cd9029301d0bd7d317cecb948efbeaf5cfe48340/src/routes/admin.rs#L196), this is a username and password-based authentication and I use it for moderating webmentions (previously comments). The password is hashed and salted. Once logged in, [I store the login status](https://codeberg.org/codingotaku/website/src/commit/5d8e3f81540c839c11117d25778be7752de10e10/src/routes/admin.rs#L217) in a private cookie.\n\nTo support the authorization confirmation screen that I will develop later, I need to modify the login page to redirect to a `URL path` when present, so I will start with that.\n\nFirst, I will accept a new optional string parameter named `redirect_path` in the login request parameter, I will use this to redirect to the `authorization endpoint`.\n\n```\n#[get(\"/login-to-site?You are receiving a request to authenticate to {{page.client_id}}
\nAfter authentication, this page will be redirected to {{page.redirect_uri}}
If this request looks suspicious, please manually verify them, or avoid authenticating the request.
\n\nLogin to Authenticate this request
\n{{/if}}\n```\n\nHere is a screenshot of the authentication page before logging in:\n\nI stopped accepting comments in favour of Webmentions a while back. This was not a decision we made lightly, especially because I put a lot of time and energy in adding comment support recently.
\nWhile I was able to fully moderate the comments and reduced the spams to near zero, I also need to be aware of the privacy concerns of the people commenting on my website.
\nI tackled this by letting people comment anonymously, but I still allow them to share their name, email, etc., if they like.
\nThere are some problems with this approach:
\nValidity:\n: I have no way to ensure that the person commenting on my website is really the person whom they are claiming to be.
\nSpams and trolls:\n: While I have managed to prevent all automated spams, people can manually troll my website, adding a gate like moderation to block this behaviour helps, but is still not good for my mental health.
\nInteractivity:\n: People usually comment and expect a response, but my previous system was treating it like shouting at the void, so it’s not a good user experience.
\nVisibility:\n: If someone comments or mentions my website on their website, that is also a comment, there is no way for me to track it unless they enter their whole comment again on my website.
\nSome of you already know this, I partially support IndieWeb on this website. One of the major things that I was missing for in it was Webmentions. Unlike supporting comments, Webmentions makes it easy to filter out things that I don’t want and works as a better gatekeeper than manual moderation (though I still moderate the Webmentions I receive).
\nWebmention is a W3 standard to let websites talk to each other, it could be a comment, like, a simple reference, or whatever. The idea is that, if “Website A” has a link that mentions “Website B”, the “Website A” or someone else can tell “Website B” about that link being referred to and by whom.
\nThis makes comments straightforward to manage, while also keeping the web do it’s original purpose of connecting to each other.
\nImplementing the Webmention is simple, I initially used the code for adding comments, and also automatically verified the link, which would’ve made my website part of a DDoS network. So I decided to remove the link verification part on a later commit. I also removed the comments in that same commit after thinking about the problems I described in the previous section.
\nThis means that my current implementation for receiving Webmention is as simple as validating the URL format and storing it in a database. I have a dedicated admin page for manually verifying it and adding it to my posts. I have a script that extracts the mention from the links I save, but I have not opened it up for the public yet (it will be done in a few weeks, so stay tuned).
\nI have not implemented sending Webmention from my website, I just use a curl command for it currently, as it is just sending a POST request with the source and target links.
# curl command to send webmention\ncurl -si protocol://the-website.tld/webmention-endpoint \\\n -d source=protocol://my-website.tld/my-mention \\\n -d target=protocol://the-website.tld/the-page-being-mentioned\nIdeally, I would have a way to crawl through my pages, extract all external links I have in it, and send a Webmention to them if I have not done that already. It’s a lot of work, and I want to integrate it to my Webmention verification script so that it can be used by everyone. I am a bit preoccupied to do that at the moment.
\nSupporting IndieAuth is the next one on my list, I already have a way to log in to this website with a password, IndieAuth would be a wrapper around it to redirect to a URL and generate a token. If I don’t end up redesigning this website, IndieAuth would be the thing you will see in my next blog post.
\n","content_text":"I stopped accepting comments in favour of [Webmentions](https://www.w3.org/TR/2017/REC-Webmention-20170112/) a while back. This was not a decision we made lightly, especially because I put a lot of time and energy in adding [comment support recently](/blogs/adding-comments).\n\n## Why remove comments?\n\nWhile I was able to fully moderate the comments and reduced the spams to near zero, I also need to be aware of the privacy concerns of the people commenting on my website.\n\nI tackled this by letting people comment anonymously, but I still allow them to share their name, email, etc., if they like.\n\nThere are some problems with this approach:\n\n**Validity:**\n: I have no way to ensure that the person commenting on my website is really the person whom they are claiming to be.\n\n**Spams and trolls:**\n: While I have managed to prevent all automated spams, people can manually troll my website, adding a gate like moderation to block this behaviour helps, but is still not good for my mental health.\n\n**Interactivity:**\n: People usually comment and expect a response, but my previous system was treating it like shouting at the void, so it's not a good user experience.\n\n**Visibility:**\n: If someone comments or mentions my website on *their* website, that is also a comment, there is no way for me to track it unless they enter their whole comment again on my website.\n\n## Why Webmention?\n\nSome of you already know this, [I partially support IndieWeb](/am-i-indieweb-yet) on this website. One of the major things that I was missing for in it was Webmentions. Unlike supporting comments, Webmentions makes it easy to filter out things that I don't want and works as a better gatekeeper than manual moderation (though I still moderate the Webmentions I receive).\n\nWebmention is a W3 standard to let websites talk to each other, it could be a comment, like, a simple reference, or whatever. The idea is that, if \"Website A\" has a link that mentions \"Website B\", the \"Website A\" or someone else can tell \"Website B\" about that link being referred to and by whom.\n\nThis makes comments straightforward to manage, while also keeping the web do it's original purpose of connecting to each other.\n\n## Implementing Webmention\n\nImplementing the Webmention is simple, I initially used the code for adding comments, and also [automatically verified the link](https://codeberg.org/codingotaku/website/src/commit/84fdb9bbfc13cb1d1852e790269cd4035be53311/src/routes/main_pages.rs#L451), which would've made my website part of a DDoS network. So I decided to remove the link verification part on a [later commit](https://codeberg.org/codingotaku/website/commit/0b39943064de72fe40a498fbb063fcecfb8bcea6). I also removed the comments in that same commit after thinking about the problems I described in the previous section.\n\nThis means that my current implementation for receiving Webmention is as simple as validating the URL format and storing it in a database. I have a dedicated admin page for manually verifying it and adding it to my posts. I have a script that extracts the mention from the links I save, but I have not opened it up for the public yet (it will be done in a few weeks, so stay tuned).\n\n## What next?\n\nI have not implemented sending Webmention from my website, I just use a `curl` command for it currently, as it is just sending a `POST` request with the source and target links.\n\n```\n# curl command to send webmention\ncurl -si protocol://the-website.tld/webmention-endpoint \\\n -d source=protocol://my-website.tld/my-mention \\\n -d target=protocol://the-website.tld/the-page-being-mentioned\n```\n\nIdeally, I would have a way to crawl through my pages, extract all external links I have in it, and send a Webmention to them if I have not done that already. It's a lot of work, and I want to integrate it to my Webmention verification script so that it can be used by everyone. I am a bit preoccupied to do that at the moment.\n\nSupporting [IndieAuth](https://indieweb.org/IndieAuth) is the next one on my list, I already have a way to log in to this website with a password, IndieAuth would be a wrapper around it to redirect to a URL and generate a token. If I don't end up redesigning this website, IndieAuth would be the thing you will see in my next blog post.","summary":"After thinking about it a long time, I have replaced the comments section on this website with Webmentions.","date_published":"2024-08-08T17:00:37Z","authors":[{"name":"Coding Otaku","url":"https://codingotaku.com/users/otaku"}]},{"id":"https://codingotaku.com/blogs/adding-comments","url":"https://codingotaku.com/blogs/adding-comments","title":"Adding Comments to My Website","content_html":"Note: I stopped accepting comments in favour of webmentions, this post is here for archiving purposes.
\nMy website is written in Rust with Rocket framework. But, just like any other website, what language or framework I use doesn’t matter here. The source code can be found at my codeberg repository.
This was a hard one to choose, I have many things planned for this website, most of which would require a high performing database. But I ended up using SQLite as it is easy to maintain and work on. Taking backups is done by a simple rsync command!
I created a table named comments and I set all columns as text, including the ID as I will be using UUID (Universally Unique IDentifier) for it. The SQL looked something like this:
CREATE TABLE IF NOT EXISTS comments (\n id TEXT NOT NULL, -- random UUID\n post TEXT NOT NULL, -- URL for the page\n name TEXT NOT NULL, -- Optional name, defaulted to anonymous\n email TEXT, -- optional email\n website TEXT, -- optional website for the commenter\n comment TEXT NOT NULL, -- the comment\n commenter TEXT NOT NULL, -- random UUID\n reply_to TEXT -- something for the future threaded replies\n)\nYou might have noticed that I did not tell SQLite to set the default value for the name field with name TEXT DEFAULT 'anonymous'. This is because of a bug I faced in the rust SQLite library I am using, the library was not converting Option::None as NULL in SQLite. So instead, I am programmatically setting the default value for now.
The comments are sent as a post request, I do some request guards there to avoid spam, more on that in the next section.
\nOne of the major concerns I have had about implementing a comment system was the spam control. I believe that I have very low traffic for this website as I don’t have analytics to confirm, and I delete access logs fairly frequently.
\nI initially just accepted all the comments. Well, you could probably guess what happened, a low traffic website means that there are more bots crawling my site than humans visiting it. I frequently received spam messages, most containing links to some pharmacy in India, and some were just trolls. The links were easy to handle, I just show plain text in comments, so none of the links were rendered as HTML to avoid the visitors and search engines navigating to it.
\nMy first plan for moderation was to send a push notification to my android phone whenever a comment was added to the website so that I can delete it quickly. I wanted to do it using UnifiedPush as I already have NextPush server hosted in my Nextcloud instance. Don’t think that it is too much work, if you have a notification server set-up, it is just a matter of sending a POST request like I did. If you do not have a server to set one up, something like ntfy.sh might interest you.
Sending myself a notification is obviously not a good way to do moderation, but it worked for me, as the frequency of spams reduced as I started deleting them immediately.
\nJust because the spams reduced doesn’t mean that I did good moderation, I was still getting spams at least once a week. It was then I decided to ask a question to the commenter, it’s a simple one to answer if they are human. And even if the answer is wrong, I return an HTTP redirect response, this will trick the bots into thinking that they succeeded. I went with this approach as I would rather not implement captcha, there are no good accessibility friendly captchas out there!
\nI never received a spam since then, I probably have missed a few real comments if the visitor couldn’t answer the question. It can be solved by adding the wrong answers to a separate table or something and moderating it later. But I don’t think it is that important for my small and humble website.
\nIn the future, I want the visitors to be able to reply to comments. I already have some work done for that in the backend, it will probably be released along with the webmention support I am working on at the moment!
\nThe posted comments will be hidden until I review and approve it. But it would be a problem for the commenter if they can’t see their own comment. So, for a slightly better user experience, the commenters can now see their comments even if it is not moderated yet, they can also edit or delete it if they’d like to.
\n![\"\"](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/07682cac-0472-436f-8d92-70097bc85be5.webp\")
This is done by storing a unique ID in a private cookie when someone comments for the first time and using it to connect to all their comments from then onwards. The ID is a randomly generated UUID.
\nMy final SQL for the comment database looks like this:
\nCREATE TABLE IF NOT EXISTS comments (\n id TEXT NOT NULL, -- random UUID\n post TEXT NOT NULL, -- URL for the page\n name TEXT NOT NULL, -- Optional name, defaulted to anonymous\n email TEXT, -- optional email\n website TEXT, -- optional website for the commenter\n comment TEXT NOT NULL, -- the comment\n commenter TEXT NOT NULL, -- random UUID\n reply_to TEXT, -- something for the future threaded replies\n date TEXT NOT NULL -- the created date, I could use the DATE type here though\n is_moderated INTEGER NOT NULL, -- Integer because SQLite doesn't support boolean.\n -- 1 means that the comment is moderated.\n)\nFor now, I think this is sufficient for my needs, even providing comments is already an overkill for my small website.
\n","content_text":"**Note:** I [stopped accepting comments](/blogs/adding-webmentions) in favour of webmentions, this post is here for archiving purposes.\n\nMy [website](/projects/website) is written in `Rust` with `Rocket` framework. But, just like any other website, what language or framework I use doesn't matter here. The source code can be found at my [codeberg repository](https://codeberg.org/codingotaku/website/).\n\n## Using SQLite for database\n\nThis was a hard one to choose, I have many things planned for this website, most of which would require a high performing database. But I ended up using `SQLite` as it is easy to maintain and work on. Taking backups is done by a simple `rsync` command!\n\nI created a table named `comments` and I set all columns as text, including the ID as I will be using [UUID](https://datatracker.ietf.org/doc/html/rfc4122) (Universally Unique IDentifier) for it. The SQL looked something like this:\n\n```\nCREATE TABLE IF NOT EXISTS comments (\n id TEXT NOT NULL, -- random UUID\n post TEXT NOT NULL, -- URL for the page\n name TEXT NOT NULL, -- Optional name, defaulted to anonymous\n email TEXT, -- optional email\n website TEXT, -- optional website for the commenter\n comment TEXT NOT NULL, -- the comment\n commenter TEXT NOT NULL, -- random UUID\n reply_to TEXT -- something for the future threaded replies\n)\n```\n\nYou might have noticed that I did not tell SQLite to set the default value for the `name` field with `name TEXT DEFAULT 'anonymous'`. This is because of a bug I faced in the rust SQLite library I am using, the library was not converting `Option::None` as `NULL` in SQLite. So instead, I am [programmatically setting](https://codeberg.org/codingotaku/website/src/commit/28c9ffa434f44e20a10870feb41672ba6c818f80/src/modals/comments.rs#L131) the default value for now.\n\nThe comments are sent as a [post request](https://codeberg.org/codingotaku/website/src/commit/28c9ffa434f44e20a10870feb41672ba6c818f80/src/routes/main_pages.rs#L282), I do some request guards there to avoid spam, more on that in the next section.\n\n## Spam control\n\nOne of the major concerns I have had about implementing a comment system was the spam control. I believe that I have very low traffic for this website as I don't have [analytics to confirm](/blogs/why-do-i-not-use-analytics), and I [delete access logs fairly frequently](/privacy).\n\nI initially just accepted all the comments. Well, you could probably guess what happened, a low traffic website means that there are more bots crawling my site than humans visiting it. I frequently received spam messages, most containing links to some pharmacy in India, and some were just trolls. The links were easy to handle, I just show plain text in comments, so none of the links were rendered as HTML to avoid the visitors and search engines navigating to it.\n\nMy first plan for moderation was to send a push notification to my android phone whenever a comment was added to the website so that I can delete it quickly. I wanted to do it using [UnifiedPush](https://unifiedpush.org/) as I already have [NextPush](https://codeberg.org/NextPush/uppush) server hosted in my [Nextcloud](https://nextcloud.com/) instance. Don't think that it is too much work, if you have a notification server set-up, it is just a matter of sending a `POST` request [like I did](https://codeberg.org/codingotaku/website/src/commit/d2ecf2a51e2fbd1f10cd72014f4bd0388caac0d9/src/routes/main_pages.rs#L310). If you do not have a server to set one up, something like [ntfy.sh](https://ntfy.sh/) might interest you.\n\nSending myself a notification is obviously not a good way to do moderation, but it worked for me, as the frequency of spams reduced as I started deleting them immediately.\n\nJust because the spams reduced doesn't mean that I did good moderation, I was still getting spams at least once a week. It was then I decided to ask a question to the commenter, it's a simple one to answer if they are human. And even if the answer is wrong, I return an HTTP [redirect response](https://codeberg.org/codingotaku/website/src/commit/d2ecf2a51e2fbd1f10cd72014f4bd0388caac0d9/src/routes/main_pages.rs#L290), this will trick the bots into thinking that they succeeded. I went with this approach as I would rather not implement captcha, there are no good accessibility friendly captchas out there!\n\nI never received a spam since then, I probably have missed a few real comments if the visitor couldn't answer the question. It can be solved by adding the wrong answers to a separate table or something and moderating it later. But I don't think it is that important for my small and humble website.\n\nIn the future, I want the visitors to be able to reply to comments. I already have some work done for that in the backend, it will probably be released along with the [webmention](https://indieweb.org/Webmention) support I am working on at the moment!\n\nThe posted comments will be hidden until I review and [approve it](https://codeberg.org/codingotaku/website/src/commit/28c9ffa434f44e20a10870feb41672ba6c818f80/src/routes/admin.rs#L189). But it would be a problem for the commenter if they can't see their own comment. So, for a slightly better user experience, the commenters can now see their comments even if it is not moderated yet, they can also edit or delete it if they'd like to.\n\nThis is part two of the series on writing a website, in the part one, “Recipe for Making a Website”, I wrote about what we can use to write a website, but not how to write one.
\nThe images in here might be unreadable when reading on devices with small screen size. This is because the images are screenshots taken from a laptop screen and resized, I have provided sufficient (or I believe they are sufficient) descriptions for them. Ideally, you should be able to get the same results in your system if you do the steps I mention in this article. If you still need to see the images, please open them in a new tab.
\nA website is usually created to provide information to a visitor. Which is typically written in text format. There are many ways to send this information to the visitor, but let us not focus on that for now, what we need is to write that information down somehow so that it can be shared.
\nBut wait, shouldn’t we figure out how to share the information first so that we can write it down in a way that it can be shared?
\nIt might seem like a chicken-and-egg problem, but fortunately for us, this is already solved. There is an existing and widely used protocol named HTTP (Hypertext Transfer Protocol) that supports transferring information through the internet, and that protocol supports a markup language called HTML, which is what we are going to use today.
\nHyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content.
\nHTML is a complex and evolving markup language, but it is easy to use because there are very few rules you need to learn to write a full-fledged website.
\nIn HTML, the structure is defined using “tags”, a tag in HTML is usually written in the format <tag-name> this is called an opening tag. An opened tag can be closed by writing the same tag and adding a / after < (e.g. </tag-name>).
An “element”, or to better word it, an “HTML element”, often consists of opening and closing tags. Everything in between those tags are called “content” of that element. For example, <q>flower</q> creates a quote element, and it is rendered as \"flower\" — here “flower” is the content.
You can place an element within another element, this is called “nesting”. But what we call it is not relevant, all you need to know is that you can infinitely nest elements! But be careful, the more nested the elements are, the more you burden the visitor’s browser and their RAM, so we must try to reduce nesting as much as possible.
\nSome elements cannot have any child (nested) element or text contents, they are called “void” elements. Void elements only have a start tag; end tags must not be specified for void elements. An example of this is the <input> tag.
Some HTML formatting tools (like prettier) try to “self-close” void tags by inserting a trailing / after the tag name (<input/>), there are some historical reasons for that, like supporting XML parsers where there are no concepts of “void” tags.
Fun fact, no browser will complain or behave weirdly if you self-close a void tag (citation needed). But self-closing is not a concept in HTML, so any tool trying to insert a self-closing tag in HTML to support XML parsers is fighting with two things that do not support each other.
\nThough no error will be thrown, there are some more restrictions on what elements can be placed in another, but let us not worry about that for now and learn different elements that we can use.
\nMost elements convey semantic meaning, and purpose. A <p> tag is used to create a paragraph element, for example. This paragraph is written in HTML, like this.
<p>\n Most elements convey semantic meaning, and purpose. A <code><p></code> tag is used to create a paragraph element, for example. This paragraph is written in HTML, like this.\n</p>\nNoticed the weird <p>? In HTML, if you want to write < or > as text, you need to escape them. This can be done by writing < and >. So <p> will create the text <p> instead of creating a tag. Modern IDEs will probably highlight them so that it will be easier to read.
There are many more characters that you can escape like this, you might be interested in reading about using character escapes in markup and CSS.
\nA good website with lots of content will have more paragraph elements than any other elements, but showing just plain text would be a bit boring and might not suit everyone’s needs or taste. There are elements to style texts within a paragraph, and some of these do similar things, but you can use them based on their semantic meaning.
\nFor example, both <i> and <em> tags are rendered (displayed) by the browser by making its content italic.\nScemantically, <i> can be used to make a text italic in style, but to emphasize a text, we should use <em> tag instead.
Other similarly styled tags are <b> and <strong>, while both of them render the text in bold, <strong> tag is used to show strong text that has a “strong importance”. And <b> tag is for, as you guessed, to make the text bold (technically, increasing the font weight).
While paragraphs are important, it is also important to have heading and subheading for the document, this makes it easier for the reader to traverse through the document.\n<h1> tag is used to show the heading of the document, a document must have only one of them (though as usual, the browser won’t stop you from having more).
You can create a subheading by increasing the number after the “h” in the heading tag, at present, it is possible to have subheadings from h2 to h6. When using them, one must not skip a heading level, i.e a h3 must not be created if there is no h2 tag present before it. The higher the number, the smaller the text, but as I already mentioned, it is used to write headings and subheadings, and not to style texts.
Now that we learned how to create text content, let us focus on putting this into a document and see it from a browser.
\nAs I mentioned at the beginning, the HTML is an evolving language, currently HTML5 is widely used, it has support for more semantic HTML elements than its prior versions. The browser must know the document format and version that we are using, this is done by using the <!DOCTYPE> declaration.\nDid you notice that I wrote “declaration” and not “tag”? This is because the declaration is not an HTML tag. It is “information” to the browser about what document type to expect.
Okay, now that we know what to do, let us create this document for real this time.
\nTo create an HTML document, any text editing software can be used. BUT, we are going to write plain text here, so it is better if you don’t use a word processor. Use a simple text editor, like ed, vi, vim, Emacs, Atom, Notepad++, or in worst-case use Sublime Text, or VS Code. But if you have opened Microsoft Word, close it, we don’t need it here.
\nCreate a new folder in your system — name it whatever you feel like, it is not relevant — now create an empty file within that folder named index.html, this time, the name is important, make sure you spelled it correctly.
The name index.html is usually looked up by most tools that can be used as a server (homework, find the historical reasoning behind it). Though we are not using any such tools at this point, we will need it in the future, so let us stick to that naming convention for now.
After creating the empty file, open it using your text editor and write the DOCTYPE to it. For HTML5, the DOCTYPE is written as <!DOCTYPE html> (yes, it is not a typo, it is html and not html5).
The HTML document has a few tags that need to be placed to be rendered properly. The first one is <html>, this is the root element of the HTML document, and there should be only one root element present in an HTML document.
Your file should now look like this:
\n<!DOCTYPE html>\n<html>\n</html>\nInside the <html> element, we can place two elements, one is <head> which can contain some additional information about the file, like the title of the document, information about the author, a brief description, how the document should be rendered, etc. For now, let us just add a title.
<!DOCTYPE html>\n<html>\n <head>\n <title>A simple HTML document</title>\n </head>\n</html>\nSimple? I will add two more things.
\nTo support more languages, we can tell the browser to use the UTF-8 character set when rendering the text by placing this meta tag within the head element:\n<meta charset=\"UTF-8\">.
To tell what language the webpage is using to the browser, and any assistive technology the visitor uses, we can use the lang attribute in the html tag:\n<html lang=\"en\">.
Just like my website, I am using the International English here, for US english, you will need to use en-us instead. To find the correct code for the language you are using, try the Language Subtag Lookup. You must do this because an empty lang tag means that the language is undefined.
The other element we can place inside the <html> is the <body> element, all contents that we write should be placed within the body.
<!DOCTYPE html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\">\n <title>A simple HTML document</title>\n </head>\n <body>\n </body>\n</html>\nWhile we can place all the contents within the body, it is a good practice to further divide the sections. For someone using assistive technology, it would be nice to have indication of different sections of the page, we call them landmarks. We are not going to use them now, just keep it in your mind, by the end of this series you will learn when and how to use them.
\nWhat you have now created is called an “HTML boilerplate”, you can copy that file content and when creating more HTML files. Some IDEs (Integrated Development Environments) can generate this (and a bit more) for you, it is up-to you to figure that out.
\nNow that the boilerplate is ready, let us put some content in it after remembering the rules:
\nh1 tag.p tag.<!DOCTYPE html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\">\n <title>A simple HTML document</title>\n </head>\n <body>\n <h1>Welcome to my simple HTML page</h1>\n <p>\n An HTML page is used for sharing information with others. And to ensure that <em>everyone</em> can access the page, we must be conscious of the <strong>semantic</strong> and <strong>accessibility</strong> when writing it.\n </p>\n </body>\n</html>\nNow save the file with the above content, once saved, you can open the index.html file using your web browser. There are many ways to do this, one way is to just drag the index.html file into the web browser. Or you might be able to right-click on the file and open it using the default browser (this flow varies between OS and Desktop environments).
Once you have opened the file in the browser, you might see something like this screenshot.
\n![\"Firefox](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/1bbd4245-ef8b-4425-be5c-b7b68f602a06.png\")
That screenshot above was very plain looking, and if you are reading my website in one of its dark themes, you might have strained your eyes, so how about we make it a bit better?
\nUnlike the structure of the website, styling is not a compulsory thing to do. But just like the structure, one should be mindful of the semantic and accessibility of the page when styling an HTML page.
\nOne of the main things that many still get wrong is the colour contrast, the default colour scheme of your website must have proper contrast. Remember, if you create a public website, or share links to it, you are effectively asking others to read it, it should not be a burden for them.
\nFixing colour contrast used to be a hard thing to do, but now there are many tools that can help one to achieve good colour contrast. One of them is WebAIM: Contrast Checker.
\nNow that we have decided to be inclusive of people with needs, let us learn how to style a web page!
\nThere are multiple ways to style elements in HTML:
\nstyle attribute<style> tag inside <head> tag.<style> placed in a separate file.We will be using a stylesheet, which is easier to read, write, and manage. The other ways I mentioned to style HTML documents are usually discouraged as it makes managing styles hard, but feel free to explore how to do them on your own.
\nA stylesheet is a simple text file that contain styles in CSS (Cascading Style Sheet) format. The purpose of CSS is to change the look and feel of the web page, but as you learn more about it, you might get tempted to ignore the HTML structure completly, we will try to avoid that here.
\nCSS is not just for styling HTML, it can be used to style SVG or XML documents, and some graphical user interface toolkits also supports styling via CSS, so it is always good to learn a bit about it.
\nFor styles to work, we need to to tell the browser where to look for it. This is done by adding a link tag within the head. The syntax will look like <link rel=\"stylesheet\" href=\"/path/to/style.css\">. As you might have noticed, link is a void tag, you do not need to close it.
The CSS has a very simple syntax, a selector, declaration block, properties, and values. There are also some more advanced things like media queries, but the basics remains the same.
\nIf you decide to have the main heading on your page to be shown in the center with red text, the following code shows a very simple CSS rule that would achieve that styling:
\nh1 {\n color: red;\n text-align: center;\n}\nh1).{ }. This is the declaration block.color in the above example) before the colon, and we specify the value of the property after the colon (red in this example).color and the other for text-align. Each pair specifies a property of the element(s) we are selecting (h1 in this case), then a value that we’d like to give to the property.Let us create a simple stylesheet first named style.css with the above example. We will create it in the same folder you placed the index.html file to.
\nNow that we have a simple css file, add it inside the head tag witin the index.html file.
<link rel=\"stylesheet\" href=\"./style.css\">\nYou will notice that the href is pointing to ./style.css. The \".\" here is to tell that the path is relative to the index.html file, and you will probably never see it on a real website because there are better ways to do this when hosting it. I will talk about that later in this blog, let us focus on the style for now.
Your index.html file should now look like this.
\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\">\n <title>A simple HTML document</title>\n <link rel=\"stylesheet\" href=\"./style.css\">\n </head>\n <body>\n <h1>Welcome to my simple HTML page</h1>\n <p>\n An HTML page is used for sharing information with others. And to ensure that <em>everyone</em> can access the page, we must be conscious of the <strong>semantic</strong> and <strong>accessibility</strong> when writing it.\n </p>\n </body>\n</html>\nOnce you save those files and refresh your browser, the content remains the same, but you will see new the style like below.
\n![\"Firefox](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/ab2bd8b3-2e24-40b8-9c3d-762fa24cd4ce.png\")
To identify which element to style, we use CSS selectors. This can be its tag name, id, class, or any other attributes.
It is also possible to style an element based on user action like when a user hover over an element, or is curruntly focusing on it with a mouse or keyboard.
The possiblities are endless, so to make a CSS stylesheet easy to read, and to reduce the burden on the browser which calculates how to style things, we should use simple selectors while also avoiding style conflicts.
\nI am going to provide some examples of selectors here, it might feel a bit overwhelming, but just like HTML elements, you do not need to understand them all. You will gradually learn as you work with them.
\nWe have already seen how to style using an element’s tag name, we just write it’s tag name, i.e., to style <h1> element, we just write h1 as its selector.
/*Styling all h1 elements */\nh1 {\n /* some styles */\n}\nThe text written between /* and */ are not considered styles, they are the way to do comments in CSS, and the browser will ignore it.
To style using an element’s attribute, we use an attribute selector, a simple attribute selector can be written as [attribute-name=\"value\"].
/* Styling all elements with the title attribute set as \"cheese\" */\n[title=\"cheese\"] {\n /* some styles */\n}\nTwo HTML attributes, id, and class are special, because they are used a lot for styling HTML.\nTo style using a class, we prefix the class name with a “.”, so the syntax will be .class-name.\nTo style using an element’s id, we prefix the class name with a “#”, so the syntax will be #element-id.
/* Styling all elements with the class \"cat\" */\n.cat {\n /* some styles */\n}\n\n/* Styling element with the id \"mouse\" */\n#mouse {\n /* some styles */\n}\nIt is also possible to join multiple selectors together, to do that, we just write them together without any space between them.
\n/* Styling all image elements with the class \"cat\" */\nimage.cat {\n /* some styles */\n}\nIf you put a space between selectors, that means that the selector preceeding is a child element. for example, the selector #house .mouse .cheese will style the element with the class cheese which is under an element with the class mouse which is under another element with the id house
/* Styling all elements with the class \"cat\" inside the element with id \"house\" */\n#house .cat {\n /* some styles */\n}\nLet us update the style.css file a bit, I’m setting a purple colour for the background, white text colour, removed the attention seeking red heading, and increased the text size for the paragraph.
\nbody {\n background-color: purple;\n color: white;\n line-height: 2em;\n}\n\nh1 {\n text-align: center;\n}\n\np {\n font-size: 1.2em;\n}\nLet us refresh the page again to see new the style.
\n![\"Firefox](\"/static/uploads/9bca2ae5-7643-4a1c-bb0c-fe37136f6cb1/e4004682-1fca-4c18-8119-33bf613f5653.png\")
Now we have a problem, the colours we set might not be readable under some light conditions, and some prefers light theme while others need a dark theme. Some set their system or the browser to automatically change the theme based on time or location. It is one of the very convenient ways to avoid eye strain.
\nWell, it is not just the visitors, you might also prefer one theme over the other most of the time. While many debate about what is good for the eyes even now, switching between dark and light themes is an accessibility feature, and we are considerate to people with needs, right?
\nMost modern browsers now support a few convenient ways to tackle this in pure CSS.
\nMedia queries\n: Media queries allow you to apply CSS styles depending on a device’s media type (such as print vs. screen) or other features or characteristics such as screen resolution or orientation, aspect ratio, browser viewport width or height, or user preferences. These may include preferences such as preferring reduced motion, data usage, or transparency.
\nCSS custom properties (CSS variables)\n: CSS variables allow you to assign property values and dynamically change it. This is a powerful feature when combined with media queries or JavaScript (A programming language used to make websites more interactive).
\ncolor-scheme property\n: The color-scheme CSS property allows an element to indicate which colour schemes it can comfortably be rendered in. This is intended to help the browser style the form controls like text boxes and buttons, and scrollbars.
\nI will write more about Media queries and dynamic styling in the next part of this series.
\n","content_text":"This is part two of the series on writing a website, in the part one, [\"Recipe for Making a Website\"](/blogs/writing-a-website-part-1), I wrote about ***what* we can use** to write a website, **but not *how* to write one**.\r\n\r\nThe images in here might be unreadable when reading on devices with small screen size. This is because the images are screenshots taken from a laptop screen and resized, I have provided sufficient (or I believe they are sufficient) descriptions for them. Ideally, you should be able to get the same results in your system if you do the steps I mention in this article. If you still need to see the images, please open them in a new tab.\r\n\r\nA website is usually created to provide information to a visitor. Which is typically written in text format. There are many ways to send this information to the visitor, but let us not focus on that for now, what we need is to write that information down somehow so that it can be shared.\r\n\r\nBut wait, shouldn't we figure out *how to share the information* first so that we can write it down in a way that it can be shared?\r\n\r\nIt might seem like a chicken-and-egg problem, but fortunately for us, this is already solved. There is an existing and widely used protocol named HTTP (Hypertext Transfer Protocol) that supports transferring information through the internet, and that protocol supports a markup language called HTML, which is what we are going to use today.\r\n\r\nHyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content.\r\n\r\nHTML is a complex and evolving markup language, but it is easy to use because there are very few rules you need to learn to write a full-fledged website.\r\n\r\n## Structuring the web page\r\n\r\nIn HTML, the structure is defined using \"tags\", a tag in HTML is usually written in the format `flower` creates a `quote` element, and it is rendered as `\"flower\"` — here \"flower\" is the content.\r\n\r\nYou can place an *element* within another *element*, this is called \"nesting\". But what we call it is not relevant, all you need to know is that you can infinitely nest elements! But be careful, the more nested the elements are, the more you burden the visitor's browser and their RAM, so we must try to reduce nesting as much as possible.\r\n\r\nSome elements cannot have any child (nested) element or text contents, they are called \"void\" elements. Void elements only have a start tag; end tags must not be specified for void elements. An example of this is the `` tag.\r\n\r\nSome HTML formatting tools (like prettier) try to \"self-close\" void tags by inserting a trailing `/` after the tag name (``), there are some historical reasons for that, like supporting XML parsers where there are no concepts of \"void\" tags.\r\n\r\nFun fact, no browser will complain or behave weirdly if you self-close a void tag (citation needed). But self-closing is **not** a concept in HTML, so any tool trying to insert a self-closing tag in HTML to support XML parsers is fighting with two things that do not support each other.\r\n\r\nThough no error will be thrown, there are some more restrictions on what elements can be placed in another, but let us not worry about that for now and learn different elements that we can use.\r\n\r\n### Scemantic elements\r\n\r\nMost elements convey semantic meaning, and purpose. A `
` tag is used to create a paragraph element, for example. This paragraph is written in HTML, like this.\r\n\r\n```\r\n
\r\n Most elements convey semantic meaning, and purpose. A tag is used to create a paragraph element, for example. This paragraph is written in HTML, like this.\r\n
`? In HTML, if you want to write `<` or `>` as text, you need to escape them. This can be done by writing `<` and `>`. So `
` will create the text `
` instead of creating a tag. Modern IDEs will probably highlight them so that it will be easier to read.\r\n\r\nThere are many more characters that you can escape like this, you might be interested in reading about [using character escapes in markup and CSS](https://www.w3.org/International/questions/qa-escapes).\r\n\r\nA good website with lots of content will have more paragraph elements than any other elements, but showing just plain text would be a bit boring and might not suit everyone's needs or taste. There are elements to style texts within a paragraph, and some of these do similar things, but you can use them based on their semantic meaning.\r\n\r\nFor example, both `` and `` tags are rendered (displayed) by the browser by making its content italic.\r\nScemantically, `` can be used to make a text *italic* in style, but to *emphasize* a text, we should use `` tag instead.\r\n\r\nOther similarly styled tags are `` and ``, **while both of them render the text in bold**, `` tag is used to show strong text that has a \"strong importance\". And `` tag is for, as you guessed, to make the text bold (technically, increasing the font weight).\r\n\r\nWhile paragraphs are important, it is also important to have heading and subheading for the document, this makes it easier for the reader to traverse through the document.\r\n` \r\n An HTML page is used for sharing information with others. And to ensure that everyone can access the page, we must be conscious of the semantic and accessibility when writing it.\r\n ` tag is used to show the heading of the document, a document must have **only one** of them (though as usual, the browser won't stop you from having more).\r\n\r\nYou can create a subheading by increasing the number after the \"h\" in the heading tag, at present, it is possible to have subheadings from `h2 to h6`. When using them, one must not skip a heading level, i.e a `h3` must not be created if there is no `h2` tag present before it. The higher the number, the smaller the text, but as I already mentioned, it is used to write headings and subheadings, and *not* to style texts.\r\n\r\n### Writing an HTML document\r\n\r\nNow that we learned *how* to create text content, let us focus on putting this into a document and see it from a browser.\r\n\r\nAs I mentioned at the beginning, the HTML is an evolving language, currently `HTML5` is widely used, it has support for more semantic HTML elements than its prior versions. The browser must know the document format and version that we are using, this is done by using the `` declaration.\r\nDid you notice that I wrote \"declaration\" and not \"tag\"? This is because the declaration is not an HTML tag. It is \"information\" to the browser about what document type to expect.\r\n\r\nOkay, now that we know what to do, let us create this document for real this time.\r\n\r\nTo create an HTML document, any text editing software can be used. BUT, we are going to write plain text here, so it is better if you don't use a word processor. Use a simple text editor, like ed, vi, vim, Emacs, Atom, Notepad++, or in worst-case use Sublime Text, or VS Code. But if you have opened Microsoft Word, close it, we don't need it here.\r\n\r\nCreate a new folder in your system — name it whatever you feel like, it is not relevant — now create an empty file within that folder named `index.html`, this time, the name is important, make sure you spelled it correctly.\r\n\r\nThe name `index.html` is usually looked up by most tools that can be used as a server (homework, find the historical reasoning behind it). Though we are not using any such tools at this point, we will need it in the future, so let us stick to that naming convention for now.\r\n\r\nAfter creating the empty file, open it using your text editor and write the DOCTYPE to it. For HTML5, the DOCTYPE is written as `` (yes, it is not a typo, it is `html` and not `html5`).\r\n\r\nThe HTML document has a few tags that need to be placed to be rendered properly. The first one is ``, this is the root element of the HTML document, and there should be only one root element present in an HTML document.\r\n\r\nYour file should now look like this:\r\n\r\n```\r\n\r\n\r\n\r\n```\r\n\r\nInside the `` element, we can place two elements, one is `` which can contain some additional information about the file, like the title of the document, information about the author, a brief description, how the document should be rendered, etc. For now, let us just add a title.\r\n\r\n```\r\n\r\n\r\n \r\n
Welcome to my simple HTML page
\r\n