├── .editorconfig ├── .gitignore ├── CNAME ├── LICENSE.md ├── README.md ├── _config.yml ├── _includes ├── footer.html ├── header.html ├── js.html └── tweet-button.html ├── _layouts └── default.html ├── _sass ├── _ads.scss ├── _og.scss └── _syntax.scss ├── cg.scss ├── code-guide-logo.png ├── code-guide-social.png ├── code-guide.svg ├── favicon.ico └── index.md /.editorconfig: -------------------------------------------------------------------------------- 1 | # editorconfig.org 2 | 3 | root = true 4 | 5 | [*] 6 | charset = utf-8 7 | end_of_line = lf 8 | indent_size = 2 9 | indent_style = space 10 | insert_final_newline = true 11 | trim_trailing_whitespace = true 12 | 13 | [*.md] 14 | trim_trailing_whitespace = false 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Ignore docs files 2 | _gh_pages 3 | _site 4 | .jekyll-cache 5 | .ruby-version 6 | .sass-cache 7 | 8 | # Numerous always-ignore extensions 9 | *.diff 10 | *.err 11 | *.orig 12 | *.log 13 | *.rej 14 | *.swo 15 | *.swp 16 | *.zip 17 | *.vi 18 | *~ 19 | 20 | # OS or Editor folders 21 | .DS_Store 22 | ._* 23 | Thumbs.db 24 | .cache 25 | .project 26 | .settings 27 | .tmproj 28 | *.esproj 29 | nbproject 30 | *.sublime-project 31 | *.sublime-workspace 32 | .idea 33 | 34 | # Komodo 35 | *.komodoproject 36 | .komodotools 37 | 38 | # grunt-html-validation 39 | validation-status.json 40 | validation-report.json 41 | 42 | # Folders to ignore 43 | node_modules 44 | bower_components 45 | -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | codeguide.co 2 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) Mark Otto. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 |
6 | Code Guide 7 |

8 | 9 |

10 | Standards for developing consistent, flexible, and sustainable HTML and CSS. 11 |
12 | Start reading ☞ 13 |

14 | 15 | --- 16 | 17 | ## Setup 18 | 19 | Code Guide is built on Jekyll and hosted on GitHub Pages. To install Jekyll: 20 | 21 | ```sh 22 | gem install jekyll 23 | ``` 24 | 25 | To start the local server: 26 | 27 | ```sh 28 | jekyll serve 29 | ``` 30 | 31 | Open `localhost:4000` in your browser. 32 | 33 | ## License 34 | 35 | Released under MIT by, and copyright, @mdo. 36 | 37 | ## Translations 38 | 39 | Translations are maintained by their creators and may not always be up to date with the original here. 40 | 41 | - [Chinese](http://zoomzhao.github.io/code-guide/) - Translated by [Zoom Zhao](https://github.com/ZoomZhao) 42 | - [Chinese](http://codeguide.bootcss.com/) - Translated by [Wang Sai](https://github.com/wangsai) 43 | - [Dutch](http://chunfeilung.github.io/code-guide/) - Translated by [Chun Fei Lung](https://github.com/chunfeilung) 44 | - [French](http://pixelastic.github.io/code-guide/) - Translated by [Tim Carry](https://github.com/pixelastic/) 45 | - [German](http://BackendButters.github.io/code-guide/) - Translated by [BackendButters](https://github.com/BackendButters) 46 | - [German](https://philipbrembeck.github.io/code-guide/) - Translated by [Philip Brembeck](https://github.com/philipbrembeck) 47 | - [Hindi](https://hidaytrahman.github.io/code-guide/) - Translated by [Hidaytullah Rahmani](https://github.com/hidaytrahman) 48 | - [Indonesian](http://diagramatics.github.io/code-guide-id) - Translated by [Steven Sinatra](http://diagramatics.me) 49 | - [Japanese](http://kia-king.com/code-guide/) - Translated by [Kia King Ishii](https://github.com/kiaking) 50 | - [Korean](http://code-guide.aliencube.org/) - Translated by [Aliencube](https://github.com/aliencube) 51 | - [Persian](https://cg.arash-hatami.ir/) - Translated by [Arash Hatami](https://github.com/hatamiarash7) 52 | - [Polish](http://bondarewicz.github.io/code-guide/) - Translated by [Łukasz Bondarewicz](https://github.com/bondarewicz) 53 | - [Portuguese](http://diegoeis.github.io/code-guide/) - Translated by [Diego Eis](http://tableless.com.br/) 54 | - [Romanian](http://vmazare.github.io/code-guide-romanian/) - Translated by [Valeriu Mazare](https://github.com/vmazare) 55 | - [Russian](http://sadcitizen.github.io/code-guide/) - Translated by [Eugene Abrosimov](https://github.com/sadcitizen) 56 | - [Spanish](https://hansfelix.github.io/code-guide) - Translated by [Hans Felix](https://github.com/hansfelix) 57 | - [Traditional Chinese](https://codeguide.intersection.tw) - Translated by [Yuming Cheung](https://github.com/ymcheung) 58 | 59 | Have a translation you'd like to link to? Open a pull request to add it here. Be sure to keep it alphabetical. 60 | 61 | <3 62 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | name: Code Guide by @mdo 2 | description: Standards for developing consistent, flexible, and sustainable HTML and CSS. 3 | url: https://codeguide.co 4 | permalink: pretty 5 | sass: 6 | style: compressed 7 | version: 4.0.0 8 | og_image: https://raw.githubusercontent.com/mdo/code-guide/gh-pages/code-guide-social.png 9 | -------------------------------------------------------------------------------- /_includes/footer.html: -------------------------------------------------------------------------------- 1 | 24 | -------------------------------------------------------------------------------- /_includes/header.html: -------------------------------------------------------------------------------- 1 | 17 | -------------------------------------------------------------------------------- /_includes/js.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /_includes/tweet-button.html: -------------------------------------------------------------------------------- 1 |

2 | 3 |

4 | -------------------------------------------------------------------------------- /_layouts/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | {{ site.name }} 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 44 | 45 | 46 | 47 | 48 | {% include header.html %} 49 | 50 |

51 | {{ content }} 52 | 53 | {% include footer.html %} 54 |

55 | 56 | {% include js.html %} 57 | 58 | 59 | -------------------------------------------------------------------------------- /_sass/_ads.scss: -------------------------------------------------------------------------------- 1 | // stylelint-disable declaration-no-important, selector-max-id 2 | 3 | // 4 | // Carbon ads 5 | // 6 | 7 | #carbonads { 8 | position: static; 9 | display: block; 10 | max-width: 400px; 11 | padding: 15px 15px 15px 160px; 12 | margin: 2rem 0 0; 13 | overflow: hidden; 14 | font-size: .8125rem; 15 | line-height: 1.4; 16 | text-align: left; 17 | background-color: var(--body-bg); 18 | border: 1px solid var(--border-color); 19 | border-radius: .5rem; 20 | 21 | a { 22 | color: var(--body-color); 23 | text-decoration: none; 24 | } 25 | } 26 | 27 | .carbon-img { 28 | float: left; 29 | margin-left: -145px; 30 | } 31 | 32 | .carbon-poweredby { 33 | display: block; 34 | margin-top: .75rem; 35 | color: var(--accent-color) !important; 36 | } 37 | -------------------------------------------------------------------------------- /_sass/_og.scss: -------------------------------------------------------------------------------- 1 | // 2 | // Global 3 | // 4 | 5 | :root { 6 | --blue: #0d6efd; 7 | --indigo: #6610f2; 8 | --purple: #6f42c1; 9 | --pink: #d63384; 10 | --red: #dc3545; 11 | --orange: #fd7e14; 12 | --yellow: #ffc107; 13 | --green: #198754; 14 | --teal: #20c997; 15 | --cyan: #0dcaf0; 16 | --white: #fff; 17 | --gray: #6c757d; 18 | --gray-dark: #343a40; 19 | 20 | --blue-300: #6ea8fe; 21 | --blue-700: #084298; 22 | 23 | --font: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; 24 | --font-heading: InterDisplay; 25 | 26 | --body-bg: #fff; 27 | --body-color: #212529; 28 | --secondary-color: #6c757d; 29 | --border-color: rgba(0, 0, 0, .1); 30 | --accent-bg: #f8f9fa; 31 | --link-color: var(--blue); 32 | --masthead-bg: var(--accent-bg); 33 | --gap: 2rem; 34 | } 35 | 36 | @media (prefers-color-scheme: dark) { 37 | :root { 38 | --body-bg: #212529; 39 | --body-color: #dee2e6; 40 | --accent-bg: #2a2f34; 41 | --link-color: var(--blue-300); 42 | --border-color: rgba(255, 255, 255, .1); 43 | } 44 | } 45 | 46 | *, 47 | *::before, 48 | *::after { 49 | box-sizing: border-box; 50 | } 51 | 52 | html { 53 | font-size: 16px; 54 | font-family: var(--font); 55 | line-height: 1.5; 56 | } 57 | 58 | body { 59 | margin: 0; 60 | color: var(--body-color); 61 | background-color: var(--body-bg); 62 | } 63 | 64 | a { 65 | color: var(--link-color); 66 | text-decoration: none; 67 | 68 | &:hover { 69 | text-decoration: underline; 70 | } 71 | 72 | code { 73 | color: inherit; 74 | } 75 | } 76 | 77 | h1, h2, h3, h4 { 78 | margin-top: 0; 79 | margin-bottom: .5rem; 80 | font-family: var(--font-heading), var(--font); 81 | font-weight: 600; 82 | line-height: 1; 83 | } 84 | h1 { font-size: 2.5rem; } 85 | h2 { font-size: 2rem; } 86 | h3 { font-size: 1.75rem; } 87 | h4 { font-size: 1.5rem } 88 | 89 | p { 90 | margin-top: 0; 91 | margin-bottom: 1rem; 92 | } 93 | 94 | blockquote { 95 | position: relative; 96 | margin: 0 1rem 1rem; 97 | font-style: italic; 98 | color: #7a7a7a; 99 | 100 | p { 101 | margin-bottom: 0; 102 | } 103 | } 104 | 105 | ul { 106 | padding-left: 1.5em; 107 | } 108 | 109 | li { 110 | padding-inline-start: 1.5ch; 111 | margin-bottom: .25rem; 112 | list-style-type: "—"; 113 | 114 | &::marker { color: var(--secondary-color); } 115 | } 116 | 117 | p:last-child, 118 | ul:last-child, 119 | blockquote:last-child { 120 | margin-bottom: 0; 121 | } 122 | 123 | 124 | // 125 | // Code 126 | // 127 | 128 | code, 129 | pre { 130 | font-family: "SFMono-Regular", Menlo, "Courier New", monospace; 131 | font-size: 95%; 132 | } 133 | code { 134 | font-size: 85%; 135 | color: var(--pink); 136 | border-radius: .2rem; 137 | } 138 | 139 | pre { 140 | display: block; 141 | margin: 0 0 1rem; 142 | line-height: 1.4; 143 | white-space: pre; 144 | white-space: pre-wrap; 145 | 146 | code { 147 | padding: 0; 148 | color: inherit; 149 | background-color: transparent; 150 | border: 0; 151 | } 152 | } 153 | 154 | .highlight { 155 | margin: 0; 156 | background-color: var(--accent-bg); 157 | 158 | pre { 159 | margin-bottom: 0; 160 | padding: var(--gap); 161 | } 162 | 163 | & + .highlight { 164 | margin-top: 1rem; 165 | } 166 | } 167 | 168 | 169 | // 170 | // Masthead 171 | // 172 | 173 | .cg-icon { 174 | display: block; 175 | width: 128px; 176 | height: 128px; 177 | margin-left: -.75rem; 178 | margin-bottom: 1.5rem; 179 | 180 | @media (min-width: 768px) { 181 | width: 192px; 182 | height: 192px; 183 | margin-left: -1.25rem; 184 | } 185 | } 186 | 187 | .cg-masthead { 188 | padding-top: 2rem; 189 | padding-bottom: 3rem; 190 | margin-bottom: 1.5rem; 191 | background-color: var(--masthead-bg); 192 | 193 | p { 194 | margin-bottom: 1rem; 195 | } 196 | 197 | @media (min-width: 960px) { 198 | padding-top: 3rem; 199 | padding-bottom: 4rem; 200 | } 201 | } 202 | 203 | .cg-masthead-title { 204 | margin-bottom: 1rem; 205 | font-size: 4rem; 206 | font-weight: 700; 207 | line-height: .9; 208 | color: inherit; 209 | 210 | @media (min-width: 768px) { 211 | font-size: 6rem; 212 | } 213 | } 214 | 215 | .cg-masthead-subtitle { 216 | max-width: 46rem; 217 | margin-bottom: 1.5rem; 218 | font-size: 1.5rem; 219 | line-height: 1.25; 220 | 221 | @media (min-width: 768px) { 222 | font-size: 2rem; 223 | } 224 | } 225 | 226 | 227 | // 228 | // Content 229 | // 230 | 231 | .container { 232 | max-width: 80em; 233 | padding-right: 2rem; 234 | padding-left: 2rem; 235 | margin-right: auto; 236 | margin-left: auto; 237 | 238 | @media (min-width: 768px) { 239 | padding-right: 3rem; 240 | padding-left: 3rem; 241 | } 242 | } 243 | 244 | .content { 245 | display: flex; 246 | flex-direction: column; 247 | gap: var(--gap); 248 | 249 | @media (min-width: 768px) { 250 | display: grid; 251 | grid-template-columns: repeat(2, 1fr); 252 | gap: calc(var(--gap) * 2) var(--gap); 253 | align-items: stretch; 254 | 255 | h2 { 256 | grid-column: auto / span 2; 257 | } 258 | 259 | .highlight { 260 | height: 100%; 261 | } 262 | } 263 | } 264 | 265 | 266 | // 267 | // The Grid 268 | // 269 | 270 | @media (min-width: 768px) { 271 | .col, 272 | blockquote { 273 | grid-column: auto / span 1; 274 | } 275 | } 276 | 277 | 278 | // 279 | // Sections 280 | // 281 | 282 | h2 { 283 | padding-top: 1rem; 284 | margin-top: 3rem; 285 | margin-bottom: 0; 286 | border-top: .25rem solid; 287 | } 288 | 289 | 290 | // 291 | // Footer 292 | // 293 | 294 | .footer { 295 | grid-column: auto / span 2; 296 | padding-top: 3rem; 297 | padding-bottom: 3rem; 298 | margin-top: 5rem; 299 | border-top: .25rem solid; 300 | } 301 | 302 | .footer p { 303 | margin-bottom: .5rem; 304 | } 305 | 306 | .quick-links { 307 | display: flex; 308 | gap: 1.25rem; 309 | list-style: none; 310 | margin-left: 0; 311 | padding-left: 0; 312 | } 313 | .quick-links li { 314 | display: inline; 315 | padding-inline-start: 0; 316 | } 317 | -------------------------------------------------------------------------------- /_sass/_syntax.scss: -------------------------------------------------------------------------------- 1 | // GitHub 2 | :root { 3 | --base00: #ffffff; 4 | --base01: #f5f5f5; 5 | --base02: #c8c8fa; 6 | --base03: #969896; 7 | --base04: #030303; 8 | --base05: #333333; 9 | --base06: #ffffff; 10 | --base07: #b08800; 11 | --base08: #ed6a43; 12 | --base09: #0086b3; 13 | --base0A: #795da3; 14 | --base0B: #183691; 15 | --base0C: #183691; 16 | --base0D: #795da3; 17 | --base0E: #a71d5d; 18 | --base0F: #333333; 19 | } 20 | 21 | // One Light 22 | // :root { 23 | // --base00: #fafafa; 24 | // --base01: #f0f0f1; 25 | // --base02: #e5e5e6; 26 | // --base03: #a0a1a7; 27 | // --base04: #696c77; 28 | // --base05: #383a42; 29 | // --base06: #202227; 30 | // --base07: #090a0b; 31 | // --base08: #ca1243; 32 | // --base09: #d75f00; 33 | // --base0A: #c18401; 34 | // --base0B: #50a14f; 35 | // --base0C: #0184bc; 36 | // --base0D: #4078f2; 37 | // --base0E: #a626a4; 38 | // --base0F: #986801; 39 | // } 40 | 41 | @media (prefers-color-scheme: dark) { 42 | // One Dark 43 | :root { 44 | --base00: #282c34; 45 | --base01: #353b45; 46 | --base02: #3e4451; 47 | --base03: #545862; 48 | --base04: #565c64; 49 | --base05: #abb2bf; 50 | --base06: #b6bdca; 51 | --base07: #d19a66; 52 | --base08: #e06c75; 53 | --base09: #d19a66; 54 | --base0A: #e5c07b; 55 | --base0B: #98c379; 56 | --base0C: #56b6c2; 57 | --base0D: #61afef; 58 | --base0E: #c678dd; 59 | --base0F: #be5046; 60 | } 61 | } 62 | 63 | .hll { background-color: #ffffff } 64 | .c { color: var(--base03) } 65 | .err { color: var(--base08) } 66 | .k { color: var(--base0E) } 67 | .l { color: var(----base09) } 68 | .n { color: var(--base08) } 69 | .o { color: var(--base08) } 70 | .p { color: var(--base05) } 71 | .cm { color: var(--base04) } 72 | .cp { color: var(--base04) } 73 | .c1 { color: var(--base03) } 74 | .cs { color: var(--base04) } 75 | .gd { color: var(--base08) } 76 | .ge { font-style: italic } 77 | .gh { color: #ffffff; font-weight: bold } 78 | .gi { color: var(--base0C) } 79 | .gp { color: var(--base04); font-weight: bold } 80 | .gs { font-weight: bold } 81 | .gu { color: var(--base0C); font-weight: bold } 82 | .kc { color: var(--base0E) } 83 | .kd { color: var(--base0E) } 84 | .kn { color: var(--base0C) } 85 | .kp { color: var(--base0E) } 86 | .kr { color: var(--base0E) } 87 | .kt { color: var(--base0A) } 88 | .ld { color: var(--base0C) } 89 | .m { color: var(--base09) } 90 | .s { color: var(--base0C) } 91 | .na { color: var(--base08) } 92 | .nb { color: var(--base05) } 93 | .nc { color: var(--base07) } 94 | .no { color: var(--base08) } 95 | .nd { color: var(--base07) } 96 | .ni { color: #ffffff } 97 | .ne { color: var(--base08) } 98 | .nf { color: var(--base0B) } 99 | .nl { color: var(--base05) } 100 | .nn { color: var(--base0A) } 101 | .nx { color: var(--base0A) } 102 | .py { color: var(--base08) } 103 | .nt { color: var(--base08) } 104 | .nv { color: var(--base08) } 105 | .ow { color: var(--base0C) } 106 | .w { color: #ffffff } 107 | .mf { color: var(--base09) } 108 | .mh { color: var(--base09) } 109 | .mi { color: var(--base09) } 110 | .mo { color: var(--base09) } 111 | .sb { color: var(--base0C) } 112 | .sc { color: #ffffff } 113 | .sd { color: var(--base04) } 114 | .s2 { color: var(--base0C) } 115 | .se { color: var(--base09) } 116 | .sh { color: var(--base0C) } 117 | .si { color: var(--base09) } 118 | .sx { color: var(--base0C) } 119 | .sr { color: var(--base0C) } 120 | .s1 { color: var(--base0C) } 121 | .ss { color: var(--base0C) } 122 | .bp { color: var(--base05) } 123 | .vc { color: var(--base08) } 124 | .vg { color: var(--base08) } 125 | .vi { color: var(--base08) } 126 | .il { color: var(--base09) } 127 | 128 | // Color commas in rgba() values 129 | .m + .o { color: var(--base03) } 130 | 131 | // Fix bash 132 | .language-sh .c { color: var(--base03) } -------------------------------------------------------------------------------- /cg.scss: -------------------------------------------------------------------------------- 1 | --- 2 | # Front matter comment to ensure Jekyll properly reads file. 3 | --- 4 | 5 | /* 6 | * Code Guide by @mdo 7 | * Licensed MIT 8 | * https://codeguide.co 9 | */ 10 | 11 | @import "ads"; 12 | @import "syntax"; 13 | @import "og"; 14 | -------------------------------------------------------------------------------- /code-guide-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdo/code-guide/6918226689cb46f6888244f1ee17389b0bd592be/code-guide-logo.png -------------------------------------------------------------------------------- /code-guide-social.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdo/code-guide/6918226689cb46f6888244f1ee17389b0bd592be/code-guide-social.png -------------------------------------------------------------------------------- /code-guide.svg: -------------------------------------------------------------------------------- 1 | 6 | -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdo/code-guide/6918226689cb46f6888244f1ee17389b0bd592be/favicon.ico -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 |

6 | 7 |

22 | 23 |

42 | 43 | ## Golden rule 44 | 45 | Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what's incorrect. For additions or contributions to this Code Guide, please [open an issue on GitHub](https://github.com/mdo/code-guide/issues/new). 46 | 47 | > Every line of code should appear to be written by a single person, no matter the number of contributors. 48 | 49 | ## HTML 50 | 51 |

52 | ### Syntax 53 | {: #html-syntax } 54 | 55 | - Don't capitalize tags, including the doctype. 56 | - Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment. 57 | - Nested elements should be indented once (two spaces). 58 | - Always use double quotes, never single quotes, on attributes. 59 | - Don't include a trailing slash in self-closing elements—the [HTML5 spec](https://html.spec.whatwg.org/multipage/syntax.html#syntax-start-tag) says they're optional. 60 | - Don’t omit optional closing tags (e.g. `` or ``). 61 |

62 | 63 | ```html 64 | 65 | 66 | 67 | Page title 68 | 69 | 70 |

71 |

Hello, world!

72 | 73 | 74 | ``` 75 | 76 |

77 | ### HTML5 doctype 78 | 79 | Enforce [standards mode](https://developer.mozilla.org/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page. In keeping with the suggested syntax, keep it lowercase. 80 | 81 |

82 | 83 | ```html 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | ``` 94 | 95 |

96 | ### Language attribute 97 | 98 | From the HTML5 spec: 99 | 100 | > Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth. 101 | 102 | Read more about the `lang` attribute [in the spec](https://html.spec.whatwg.org/multipage/semantics.html#the-html-element). Head to the IANA for a [list of language codes](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). 103 |

104 | 105 | ```html 106 | 107 | 108 | 109 | ``` 110 | 111 |

112 | ### IE compatibility mode 113 | 114 | There's no need to include the Internet Explorer document compatibility `` tag these days, unless you need support for IE10 and older. The tag was dropped in IE11 and isn't used in Microsoft Edge (legacy or otherwise). 115 | 116 | For more information, [read this awesome Stack Overflow article](https://stackoverflow.com/questions/6771258/what-does-meta-http-equiv-x-ua-compatible-content-ie-edge-do). 117 |

118 | 119 | ```html 120 | 121 | 122 | ``` 123 | 124 |

125 | ### Character encoding 126 | 127 | Ensure proper content rendering by declaring an explicit character encoding. This also allows you to use regular characters instead of their HTML entities, like `—` instead of `&emdash;`, provided their encoding matches that of the document. For some reserved XML characters—like ampersand, non-breaking spaces, less/greater than, and quotes—you may still need to use the HTML character entities. 128 | 129 | UTF-8 is the recommended encoding. 130 |

131 | 132 | ```html 133 | 134 | 135 | 136 | 137 |

Use an em dash like so—no HTML entity required.

138 | 139 | ``` 140 | 141 |

142 | ### CSS and JavaScript includes 143 | 144 | Per HTML5 spec, typically there is no need to specify a `type` when including CSS and JavaScript files as `text/css` and `text/javascript` are their respective defaults. 145 | 146 | #### HTML5 spec links 147 | 148 | - [Using link](https://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-link-element) 149 | - [Using style](https://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-style-element) 150 | - [Using script](https://www.w3.org/TR/2011/WD-html5-20110525/scripting-1.html#the-script-element) 151 |

152 | 153 | ```html 154 | 155 | 156 | 157 | 158 | 161 | 162 | 163 | 164 | ``` 165 | 166 |

167 | ### Practicality over purity 168 | 169 | Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible. 170 |

171 | 172 | ```html 173 | 174 | 175 | 176 | 177 |

...

178 | ``` 179 | 180 |

196 | 197 | ```html 198 | 199 | Example link 200 | 201 | 202 | 203 | 204 |

205 | ``` 206 | 207 |

208 | ### Boolean attributes 209 | 210 | A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement. 211 | 212 | For further reading, consult the [WhatWG section on boolean attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes) 213 | 214 | > The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value. 215 | 216 | If you must include the attribute's value, and **you don't need to**, follow this WhatWG guideline: 217 | 218 | > If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace. 219 | 220 | In short, **don't add a value**. 221 |

222 | 223 | ```html 224 | 225 | 226 | 227 | 228 | 231 | ``` 232 | 233 |

234 | ### Reduce markup 235 | 236 | Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. 237 |

238 | 239 | ```html 240 | 241 | 242 |

243 | 244 | 245 | 246 |

247 | ``` 248 | 249 |

250 | ### Editor preferences 251 | 252 | Set your editor to the following settings to avoid common code inconsistencies and dirty diffs: 253 | 254 | - Use soft-tabs set to two spaces. 255 | - Trim trailing white space on save. 256 | - Set encoding to UTF-8. 257 | - Add new line at end of files. 258 | 259 | Consider documenting and applying these preferences to your project's `.editorconfig` file. For an example, see [the one in Bootstrap](https://github.com/twbs/bootstrap/blob/main/.editorconfig). Learn more [about EditorConfig](https://editorconfig.org). 260 |

261 | 262 | ## CSS 263 | 264 |

265 | ### Syntax 266 | {: #css-syntax } 267 | 268 | - Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment. 269 | - When grouping selectors, keep individual selectors to a single line. 270 | - Include one space before the opening brace of declaration blocks for legibility. 271 | - Place closing braces of declaration blocks on a new line. 272 | - Include one space after `:` for each declaration. 273 | - Each declaration should appear on its own line for more accurate error reporting. 274 | - End all declarations with a semi-colon. The last declaration's is optional, but your code is more error prone without it. 275 | - Comma-separated property values should include a space after each comma (e.g., `box-shadow`). 276 | - Use space-separated values for color properties (e.g., `color: rgb(0 0 0 / .5)`). [See the Colors section for more information.](#colors) 277 | - Don't prefix property values or color parameters with a leading zero (e.g., `.5` instead of `0.5` and `-.5px` instead of `-0.5px`). 278 | - Lowercase all hex values, e.g., `#fff`. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes. 279 | - Use shorthand hex values where available, e.g., `#fff` instead of `#ffffff`. 280 | - Quote attribute values in selectors, e.g., `input[type="text"]`. [They’re only optional in some cases](https://mathiasbynens.be/notes/unquoted-attribute-values#css), and it’s a good practice for consistency. 281 | - Avoid specifying units for zero values, e.g., `margin: 0;` instead of `margin: 0px;`. 282 | 283 | Questions on the terms used here? See the [syntax section of the Cascading Style Sheets article](https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax) on Wikipedia. 284 |

285 | 286 | ```scss 287 | // Bad CSS 288 | .selector, .selector-secondary, .selector[type=text] { 289 | padding:15px; 290 | margin:0px 0px 15px; 291 | background-color:rgba(0, 0, 0, 0.5); 292 | box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF 293 | } 294 | 295 | // Good CSS 296 | .selector, 297 | .selector-secondary, 298 | .selector[type="text"] { 299 | padding: 15px; 300 | margin-bottom: 15px; 301 | background-color: rgb(0 0 0 / .5); 302 | box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff; 303 | } 304 | ``` 305 | 306 |

307 | ### Declaration order 308 | 309 | Property declarations should be grouped together in the following order: 310 | 311 | 1. Positioning 312 | 2. Box model 313 | 3. Typographic 314 | 4. Visual 315 | 5. Misc 316 | 317 | Positioning comes first because it can remove an element from the normal document flow and override box model related styles. The box model—whether it's flex, float, grid, or table—follows as it dictates a component's dimensions, placement, and alignment. Everything else takes place _inside_ the component or without impacting the previous two sections, and thus they come last. 318 | 319 | While `border` is part of the box model, most systems globally reset the [`box-sizing`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) to `border-box` so that `border-width` doesn't affect overall dimensions. This, combined with keeping `border` near `border-radius`, is why it's under the Visual section instead. 320 | 321 | Preprocessor mixins and functions should appear wherever most appropriate. For example, a `border-top-radius()` mixin would go in place of `border-radius` properties, while a `responsive-font-size()` function would go in place of `font-size` properties. 322 | 323 | For a complete list of properties and their order, please see the [property order for Stylelint](https://github.com/stormwarning/stylelint-config-recess-order) used by [Bootstrap](https://getbootstrap.com). 324 |

325 | 326 | ```scss 327 | .declaration-order { 328 | // Positioning 329 | position: absolute; 330 | top: 0; 331 | right: 0; 332 | bottom: 0; 333 | left: 0; 334 | z-index: 100; 335 | 336 | // Box model 337 | display: flex; 338 | flex-direction: column; 339 | justify-content: center; 340 | align-items: center; 341 | width: 100px; 342 | height: 100px; 343 | 344 | // Typography 345 | font: normal 14px "Helvetica Neue", sans-serif; 346 | line-height: 1.5; 347 | color: #333; 348 | text-align: center; 349 | text-decoration: underline; 350 | 351 | // Visual 352 | background-color: #f5f5f5; 353 | border: 1px solid #e5e5e5; 354 | border-radius: 3px; 355 | 356 | // Misc 357 | opacity: 1; 358 | } 359 | ``` 360 | 361 |

362 | ### Logical properties 363 | 364 | Logical properties are alternatives to directional and dimensonal properties based on abstract terms like *block* and *inline*. By default, block refers to the vertical direction (top and bottom) while inline refers to the horizontal direction (right and left). You can begin to use these values in your CSS in all modern, evergreen browsers. 365 | 366 | **Why use logical properties?** Not every language flows left-ro-right like English, so the [writing mode](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode) needs to be flexible. With logical properties, you can easily support languages that can be written horizontally or vertically (like Chinese, Japanese, and Korean). Plus, they're usually shorter and simpler to write. 367 | 368 | **Additional reading:** 369 | 370 | - [CSS Logical Properties and Values – MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties) 371 | - [CSS Logical Properties and Values — CSS Tricks](https://css-tricks.com/css-logical-properties-and-values/) 372 | - [CSS Writing Modes – MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Writing_Modes) 373 |

374 | 375 | ```scss 376 | // Without logical properties 377 | .element { 378 | margin-right: auto; 379 | margin-left: auto; 380 | border-top: 1px solid #eee; 381 | border-bottom: 1px solid #eee; 382 | } 383 | 384 | // With logical properties 385 | .element { 386 | margin-inline: auto; 387 | border-block: 1px solid #eee; 388 | } 389 | ``` 390 | 391 |

392 | ### Colors 393 | 394 | With the support of [CSS Color Levels 4](https://www.w3.org/TR/css-color-4/) [in all major browsers](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb#space-separated_values), `rgba()` and `hsla()` are now aliases for `rgb()` and `hsl()`, meaning you can modify alpha values in `rgb()` and `hsl()`. Along with this comes support for new space-separated syntax for color values. For compability with future CSS color functions, use this new syntax. 395 | 396 | Regardless of your color values and syntax, always ensure your color choices meet [WCAG minimum contrast ratios](https://webaim.org/articles/contrast/) (4.5:1 for 16px and smaller, 3:1 for larger). 397 | 398 | **Additional reading:** 399 | 400 | - [Smashing Magazine - A Guide To Modern CSS Colors](https://www.smashingmagazine.com/2021/11/guide-modern-css-colors/) 401 | - [`rgb()` - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb) 402 |

403 | 404 | ```css 405 | .element { 406 | color: rgb(255 255 255 / .65); 407 | background-color: rgb(0 0 0 / .95); 408 | } 409 | ``` 410 | 411 |

412 | ### Avoid `@import`s 413 | 414 | Compared to ``s, `@import` is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach: 415 | 416 | - Use multiple ``elements 417 | - Compile your CSS with a preprocessor like [Sass](https://sass-lang.com/) or [Less](https://lesscss.org/) into a single file 418 | - Concatenate your CSS files with features provided in Rails, Jekyll, and other environments 419 | 420 | For more information, [read this article by Steve Souders](https://www.stevesouders.com/blog/2009/04/09/dont-use-import/). 421 |

422 | 423 | ```html 424 | 425 | 426 | 427 | 428 | 431 | ``` 432 | 433 |

434 | ### Media query placement 435 | 436 | Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future. Here's a typical setup. 437 |

438 | 439 | ```css 440 | .element { ... } 441 | .element-avatar { ... } 442 | .element-selected { ... } 443 | 444 | @media (min-width: 480px) { 445 | .element { ... } 446 | .element-avatar { ... } 447 | .element-selected { ... } 448 | } 449 | ``` 450 | 451 |

452 | ### Single declarations 453 | 454 | In instances where a rule set includes **only one declaration**, consider removing line breaks for readability and faster editing. Any rule set with multiple declarations should be split to separate lines. 455 | 456 | The key factor here is error detection—e.g., a CSS validator stating you have a syntax error on Line 183. With a single declaration, there's no missing it. With multiple declarations, separate lines is a must for your sanity. 457 |

458 | 459 | ```scss 460 | // Single declarations on one line 461 | .span1 { width: 60px; } 462 | .span2 { width: 140px; } 463 | .span3 { width: 220px; } 464 | 465 | // Multiple declarations, one per line 466 | .sprite { 467 | display: inline-block; 468 | width: 16px; 469 | height: 15px; 470 | background-image: url("../img/sprite.png"); 471 | } 472 | .icon { background-position: 0 0; } 473 | .icon-home { background-position: 0 -20px; } 474 | .icon-account { background-position: 0 -40px; } 475 | ``` 476 | 477 |

478 | ### Shorthand notation 479 | 480 | Limit shorthand declaration usage to instances where you must explicitly set all available values. Frequently overused shorthand properties include: 481 | 482 | - `padding` 483 | - `margin` 484 | - `font` 485 | - `background` 486 | - `border` 487 | - `border-radius` 488 | 489 | Usually we don't need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. A `0` value implies an override of either a browser default or previously specified value. 490 | 491 | Excessive use of shorthand properties leads to sloppier code with unnecessary overrides and unintended side effects. 492 | 493 | The Mozilla Developer Network has a great article on [shorthand properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) for those unfamiliar with notation and behavior. 494 |

495 | 496 | ```scss 497 | // Bad example 498 | .element { 499 | margin: 0 0 10px; 500 | background: red; 501 | background: url("image.jpg"); 502 | border-radius: 3px 3px 0 0; 503 | } 504 | 505 | // Good example 506 | .element { 507 | margin-bottom: 10px; 508 | background-color: red; 509 | background-image: url("image.jpg"); 510 | border-top-left-radius: 3px; 511 | border-top-right-radius: 3px; 512 | } 513 | ``` 514 | 515 |

516 | ### Nesting in preprocessors 517 | 518 | Avoid unnecessary nesting in preprocessors whenever possible—keep it simple and avoid reverse nesting. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested. 519 | 520 | **Additional reading:** 521 | 522 | - Nesting in Sass and Less 523 |

524 | 525 | ```scss 526 | // Without nesting 527 | .table > thead > tr > th { … } 528 | .table > thead > tr > td { … } 529 | 530 | // With nesting 531 | .table > thead > tr { 532 | > th { … } 533 | > td { … } 534 | } 535 | ``` 536 | 537 |

538 | ### Operators in preprocessors 539 | 540 | For improved readability, wrap all math operations in parentheses with a single space between values, variables, and operators. 541 |

542 | 543 | ```scss 544 | // Bad example 545 | .element { 546 | margin: 10px 0 @variable*2 10px; 547 | } 548 | 549 | // Good example 550 | .element { 551 | margin: 10px 0 (@variable * 2) 10px; 552 | } 553 | ``` 554 | 555 |

556 | ### Comments 557 | 558 | Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name. Use the `//` syntax when writing CSS with preprocessors. When shipping CSS to production, remove all comments. 559 | 560 | Be sure to write in complete sentences for larger comments and succinct phrases for general notes. 561 |

562 | 563 | ```scss 564 | // Bad example 565 | // Modal header 566 | .modal-header { 567 | ... 568 | } 569 | 570 | // Good example 571 | // Wrapping element for .modal-title and .modal-close 572 | .modal-header { 573 | ... 574 | } 575 | ``` 576 | 577 |

578 | ### Class names 579 | 580 | - Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (e.g., `.btn` and `.btn-danger`). 581 | - Avoid excessive and arbitrary shorthand notation. `.btn` is useful for _button_, but `.s` doesn't mean anything. 582 | - Keep classes as short and succinct as possible. 583 | - Use meaningful names; use structural or purposeful names over presentational. 584 | - Prefix classes based on the closest parent or base class. 585 | - Use `.js-*` classes to denote behavior (as opposed to style), but keep these classes out of your CSS. 586 | 587 | It's also useful to apply many of these same rules when creating custom properties and preprocessor variable names. 588 |

589 | 590 | ```scss 591 | // Bad example 592 | .t { ... } 593 | .red { ... } 594 | .header { ... } 595 | 596 | // Good example 597 | .tweet { ... } 598 | .important { ... } 599 | .tweet-header { ... } 600 | ``` 601 | 602 |

603 | ### Selectors 604 | 605 | - Use classes over generic element tags for more explicit and reliable styling that isn't dependent on your markup. 606 | - Avoid using several attribute selectors (e.g., `[class^="..."]`) on commonly occuring components. Browser performance is known to be impacted by these. 607 | - Keep selectors short and strive to limit the number of elements in each selector to three. 608 | - Scope classes to the closest parent `only` when necessary (e.g., when not using prefixed classes). 609 | 610 | **Additional reading:** 611 | 612 | - [Scope CSS classes with prefixes](https://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/) 613 | - [Stop the cascade](https://markdotto.com/2012/03/02/stop-the-cascade/) 614 |

615 | 616 | ```scss 617 | // Bad example 618 | span { ... } 619 | .page-container #stream .stream-item .tweet .tweet-header .username { ... } 620 | .avatar { ... } 621 | 622 | // Good example 623 | .avatar { ... } 624 | .tweet-header .username { ... } 625 | .tweet .avatar { ... } 626 | ``` 627 | 628 |

629 | ### Child and descendant selectors 630 | 631 | When necessary, it may be helpful to use [the child combinator (`>`)](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_combinator) to limit the cascade of some styles in elements like ``s that are often recursively nested. Use it to limit styles to the immediate children elements of a parent element to avoid unnecessary overrides later on. 632 | 633 | 634 | ```css 635 | .custom-table > tbody > tr > td, 636 | .custom-table > tbody > tr > th { 637 | /* ... */ 638 | } 639 | ``` 640 | 641 |

642 | ### Organization 643 | 644 | - Organize sections of code by component. 645 | - Develop a consistent commenting hierarchy. 646 | - Use consistent white space to your advantage when separating sections of code for scanning larger documents. 647 | - When using multiple CSS files, break them down by component instead of page. Pages can be rearranged and components moved. 648 |

649 | 650 | ```scss 651 | // 652 | // Component section heading 653 | // 654 | 655 | .element { ... } 656 | 657 | 658 | // 659 | // Component section heading 660 | // 661 | // Sometimes you need to include optional context for the entire component. Do that up here if it's important enough. 662 | // 663 | 664 | .element { ... } 665 | 666 | // Contextual sub-component or modifer 667 | .element-heading { ... } 668 | ``` 669 | --------------------------------------------------------------------------------

2 | 3 | 4 | 5 |
6 | Code Guide 7 |

5 | Code Guide 6 |

Table of contents

Hello, world!

2 | 3 | 4 | 5 | 6 | Code Guide 7 |

Table of contents

Hello, world!

2 | 3 | 4 | 5 |
6 | Code Guide 7 |