Keep your CSS/SASS files organised with a Table of Contents

If you’re like me, I like to keep things organised (except for my office according to my wife), so I thought I’d share what I do to keep my SASS files tidy on my WordPress projects. This same idea can be used to organise normal CSS files too so don’t hesitate to adapt it to your needs. It really is super easy and basic to do and sets a great foundation for your project.

I’m always look at ways to improve what I write. We all know commenting your code is best practice — especially if you work in a team. What I’ve found is, by introducing a table of contents into your project it really makes it easy for not only you, but also any team members or third party developers down the line to locate and understand what you’ve written. For anyone walking into a project, this is greatly appreciated!

So to kick off, this is the Table of Contents I put into my base style.scss file. You could also put this at the top of your style.css file if you don’t use SASS.

/** TABLE OF CONTENTS
 — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — /
1 — Global Styles
1.1 — General Rules
1.2 — Colors
1.3 — Testimonial Slider
2 — Layout
2.1 — Header
2.2 — Menu
3 — Page Specific CSS
3.1 — Service Single Layout
4 — Forms
4.1 — Contact Form
5 — Admin Branding
5.1 — Admin Bar
5.2 — Builder Styles
/// END TABLE OF CONTENTS **/

Then underneath it, the only other thing I would do is import all my partial SCSS files so it ends up looking like this (this step wouldn’t apply to plain CSS).

/** TABLE OF CONTENTS
------------------------------------------------------------/
1 - Global Styles
1.1 - General Rules
1.2 - Colors
1.3 - Testimonial Slider
2 - Layout
2.1 - Header
2.2 - Menu
3 - Page Specific CSS
3.1 - Service Single Layout
4 - Forms
4.1 - Contact Form
5 - Admin Branding
5.1 - Admin Bar
5.2 - Builder Styles
/// END TABLE OF CONTENTS **/
@import 'global';
@import 'layout';
@import 'page-specific';
@import 'forms';
@import 'admin-branding';

This is how my folder structure looks like with the child theme as the parent folder;

├── style.css
├── /assets/
|   └── /scss/
|       ├── _global.scss
|       ├── _layout.scss
|       ├── _page-specific.scss
|       ├── _forms.scss
|       └── _admin-branding.scss

So now we have our table of contents done and our folder structure setup with the correct partial files, here is an example of what the _global.scss would look like.

/** 1 - Global Settings
------------------------------------------------------------*/
/* =========================
1.1 - General
========================= */
.no-margin p {
   margin-bottom: 0;
}
/* =========================
1.2 - Colors
========================= */
$white: #ffffff;
$black: #000000;
$dark-grey: #111111;

It really is that simple. For normal CSS you wouldn’t use partial files and just have all the sections in order running down your style.css stylesheet but it now makes it far easier to find any rules you’ve previously written. All you need to do is CMD+F or CTRL+F and search the section you are looking for in your code editor of choice.

If you are using just normal CSS, you may want to make an extra section for tablet responsive styles and mobile responsive styles. In SASS we can write the media query in one rule so we don’t need a separate section for this but it may be handy for you.

This is really just a starting point and you can totally customise it to your needs/workflow and I promise you, it will make your life easier in the long run!

Comments

[Louise]

Awesome article. I create sections like that in CSS but never thought of a TOC and numbered them. Instead of adding responsive stylings at the bottom, I usually create a new file (responsive.css) for them.