### Markdown Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to valid HTML. [Markdown Guide](https://www.markdownguide.org/) [Markdown Simulator](https://daringfireball.net/projects/markdown/dingus) Markdown is often used in [_static site generator_](./staticsites.html) platforms like Jekyll or Hugo. The downside to these platforms is that you have to install their software, and then use command line tools to locally build (i.e. convert to HTML) your site before you push it to the web. This page is created using a library called [Strapdown](https://strapdownjs.com/). The advantage of Strapdown is that it converts MD to HTML on the fly, so we don't need to do anything in command line. All we have to do is wrap the Markdown text in `<xmp>` tags add a reference to the library on any page we want to convert: `<script src="https://strapdownjs.com/v/0.2/strapdown.js"> </script>` ### HTML The nice thing about working in Markdown is that it doesn't preclude using HTML elements directly. I can switch back and forth between MD and HTML as I write my .html file -- the end result will be 100% HTML. Some elements aren't handled well by Markdown, like embedding a youtube video using the [iframe](https://www.w3schools.com/tags/tag_iframe.ASP) tag, so we can do things like that with HTML. HTML is not difficult to learn, but there's no reason to memorize the elements. Whenever I need to remember the syntax for an HTML element, I just look up the reference on [w3schools](https://www.w3schools.com/html/default.asp) (there are plenty of similar resources as well). ### Bootstrap Bootstrap is (apparently) the most popular HTML, CSS, and JavaScript framework for creating responsive, mobile-first websites. Notably, Bootstrap relies on a 12-column grid system for organizing page layouts in a way that looks good on screens of all sizes. Bootstrap is not necessary for every site. A page like this one is intended to be used for taking notes -- a single column is fine. On the other hand, sometimes you'll want an attractive and responsive grid layout, especially as a [home/landing page](https://nathanmelenbrink.github.io/howtodesign/) (notice how the page layout changes as you change the browser window size). It's completely reasonable to use Bootstrap for your home page, but stick to a simple single-column layout (i.e., no Bootstrap) for individual project pages. Learn more about Bootstrap on [w3schools](https://www.w3schools.com/bootstrap5/bootstrap_get_started.php). Note that there isn't much difference between Bootstrap 3, 4, and 5. If you're writing a page from scratch, it's best to use the most current version. If you're working with a template you found, it's best to stick with the version the template was made with. Strapdown is designed to work with Bootstrap layouts. This page is rendered using the "journal" theme, but I can choose from many others (see [bootswatch](https://bootswatch.com/) for examples). All I have to do is change the theme in the `<xmp>` tag: `<xmp theme="journal" style="display:none;">` Sometimes, we'll want to make small changes to a theme (font size, colors, margins, etc.). We can do that using CSS (see below).  ### CSS / SCSS CSS (cascading style sheets) is the canonical way of styling HTML pages. CSS is kind of dumb and tedious, so people make CSS extension languages to help automate styling changes. [Sass](https://sass-lang.com/) claims to be the most mature, stable, and powerful professional grade CSS extension language in the world. However, working with Sass/SCSS requires a bit of setup and command line work -- for beginners, it's probably best to stick with CSS. You can apply CSS styles to a single HTML element, a single HTML page, or the entire website directory. The latter is more useful for changing overall styling, but sometimes you want to just edit one element using inline styling, for example to change the color of a header (this requires HTML, not MD): `<h3 style="color:blue;text-align:center;">Column 3</h3>` renders as: <h3 style="color:blue;text-align:center;">Column 3</h3> In order to make changes that apply to the entire website directory, we should make a new file in the root of the directory. I'll call mine `custom.css`. In this new file, I can start to make changes that will be applied globally (to my whole website). Note that in order to implement these styles, I will need to link to my stylesheet by pasting the following line of code after the strapdown script reference: `<link rel="stylesheet" href="custom.css">` Now, if I edit the contents of my `custom.css` file to do something like apply a lightblue background to the entire website (all other elements are "children" of the `body` element, and therefore receive its styling by default): ``` body { background-color: lightblue; } ``` Okay great. But what if I want to change the styling of all `<h3>` elements in my website? These elements are written in Markdown, then converted to HTML by Strapdown. Let's add this code to my CSS file: ``` h3{ color: navy; margin-left: 20px; } ``` If you refresh your page, you'll notice that the `margin-left` attribute has changed for all of the `<h3>` elements we created in MD using `###`. However, the color has not changed to `navy`. What's up with that? It's because our Bootswatch template is overriding those colors with its own styles. It's styling doesn't include a `margin-left` attribute, so our `20px` is applied. If we want our `navy` color to not be overridden, we can apply an `important!` flag, like this: ``` h3{ color: navy important!; margin-left: 20px; } ``` That ought to render like we'd expect.