hypertext, words and more

Website Development

  • Okay, so it’s been a while since last time I wrote about Roots (shoutout to Rob for pointing it out). The last time I wrote about the Roots Stack, things were more or less the same. But I felt compelled to write this guide ever since Sage got a version bump.

    Secondly, no one enjoys spending precious hours configuring their local setup using a MAMP GUI or fucking up your machine’s hosts file or deliberating on how to fix the dreaded error establishing a database connection. What I love most about Roots is the priority on convention over configuration. 

    It’s literally a playbook taken from Rails. The net gain of this philosophy is twofold:

    1. Lowered barrier to entry for beginners
    2. Productivity bonus, spend more time hacking and less time crying

    The Roots framework has huge benefits for beginners, and even bigger returns for WordPress veterans. Mainly because you’ll no longer have to FTP your deployments like a goddamn barbarian. But I’ll go into more detail on remote server setup in my next post.

    Before I get side-tracked, let’s just dive right in shall we?


    Let’s talk about requirements and assumptions. I’m assuming you’re using Sublime Text 3 (all other versions make sure you have this enabled) and you understand how to use your terminal. Follow the links below and install the following software.


    Below is what we want our project too roughly look like:      # → Root folder for the project
    ├── trellis/      # → You'ver clone of Trellis
    └── site/         # → A Bedrock-based WordPress site (cloned as well)
        └── web/
            ├── app/  # → WordPress content directory (themes, plugins, etc.)
            └── wp/   # → WordPress core (don't touch!)

    Create a Sites folder if you haven’t already. I typically put all of my web projects in a Sites folder in my home directory on my Mac. To get started, we’re going to make a directory called — you can name yours whatever project name you’d like:

    cd ~/Sites && mkdir && cd

    You should be inside the directory at this point. Next we’re going to clone Trellis:

    git clone --depth=1 && rm -rf trellis/.git

    Then we’re going to clone Bedrock (which contains WP Core and our web app, etc.):

    git clone --depth=1 site && rm -rf site/.git

    At this point, our directory should look like this:      # → Root folder for the project
    ├── trellis/      # → You'ver clone of Trellis
    └── site/         # → A Bedrock-based WordPress site (cloned as well)

    You’ve’re doing great!

    Trellis vars

    Now let’s get into something a bit more challenging. We’re going into the Trellis directory and need to edit some variables to bring this local WordPress installation to life. I’m assuming you have Sublime Text 3 installed and you’re still in the root of

    Edit the wordpress_sites.yml file first:

    subl trellis/group_vars/development/wordpress_sites.yml

    Then just make sure it looks like this. Replace with the name of the project you have chosen. This is pretty important at this point, as we start getting into the nitty-gritty.

    # Make sure your file looks like this
          - canonical: example.test
              - www.example.test
        local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
        admin_email: admin@example.test
          enabled: false
          enabled: false
          provider: self-signed
          enabled: false

    Now go ahead and edit the vault.yml file as well:

    subl trellis/group_vars/development/vault.yml
    # Make sure the site name (``) must match up with the site name
    # in the file we previously edited: `group_vars/development/wordpress_sites.yml`
    # By default Trellis will provision a user `admin` too, below you can set a different
    # password if you'd like
        admin_password: admin
          db_password: example_dbpassword

    Don’t worry about the other .yml files in the development folder for now.


    Vagrant is our savior. It sits between us and the VirtualBox, and does most of the talking. To get our machine running our new local setup we configured (in the wordpress_sites.yml and vault.yml files), we have to go down into our trellis directory and get vagrant running:

    cd trellis && vagrant up

    By now you should see this a few commands trickling in. At some point vagrant will ask for your sudo password because it needs root permissions.

    Enter your password and vagrant will begin installing, provisioning and start running tasks your virtual-machine.

    At this point, take a break and chill. The total installation/provision time varies from machine to machine, but it takes around 10-15 minutes on a mid-2015 13″ MacBook Pro. Once the provisioner is done (provided that no errors stopped the installation), you can open your browser and navigate to example.test and you should see this:

    Getting started with theme development with Sage

    Now that we have a local development environment setup and running, we can move onto creating our first theme! The Roots team put together an awesome starter-theme to speed up development.

    Remember our project structure? We’re going to cd our way into the themes directory:      # → Root folder for the project
    ├── trellis/      # → Trellis
    └── site/         # → A Bedrock-based WordPress site
        └── web/
            ├── app/  # → WordPress content directory (themes, plugins, etc.)
            |   ├── mu-plugins/  # Must-use plugins live here
            |   ├── plugins/     # Plugins live here, managed by composer.json in the `site` folder
            |   ├── themes/      # We're going to create our theme HERE.
            |   └── uploads/     # WordPress will put uploads here (I wouldn't mess with these)
            └── wp/   # → WordPress core (don't touch! Like ever!)

    Once we’re in the themes directory, we’re going to run a composer command:

    composer create-project roots/sage example-theme 8.5.3

    Basically, the previous command says:

    1. create a composer project with the the roots/sage package
    2. name the theme, “example-theme”
    3. choose the 8.5.3 version of the roots/sage package

    As of October 17, 2017 the LTS Sage version is at 8.5.3 which is why I chose that version. You should see composer downloading the packages (be patient, sometimes composer can be slow)

    Sage requires Node.js to function. Make sure you are up-to-date.

    npm install -g npm@latest

    We’re going to use Gulp to build assets (styles, scripts, etc) and Bower will handle any front-end packages such as Bootstrap or Flickity. To get started, cd inside our new theme example-theme. We’re going to install Gulp and Bower globally (if you haven’t already)

    npm install -g gulp bower

    Now, were’ going to install all the dependencies listed in the package.json

    npm install && bower install

    Next, let’s open our manifest.json in Sublime Text and configure BrowserSync to proxy our dev URL

    subl assets/manifest.json

    Make sure the devURL reflects the canonical hostname we wrote in wordpress_sites.yml earlier since our vagrant machine will be listening for traffic at that URL.

      "config": {
        "devUrl": "http://example.test"

    At this point, we can go to example.test/wp-admin, and login. From the dashboard, choose Appearance > Themes. Pick your Sage Theme and Visit Site. Everything will look broken now, as no styles exist 🙁

    But don’t fret! Next, we go back to the terminal (make sure you’re still in the new theme directory), and run gulp watch. A new tab should open on your browser. That’s BrowserSync loading style changes in real-time (no more ⌘R in Chrome). Save any of the SCSS files in the assets/styles directory and your webpage should reload with the changes. Also watch your terminal 👀

    Gulp literally watches all PHP, SCSS and JS files changes. And BrowserSync will reload your browser window. Pretty nifty. Assuming you didn’t get any errors, your homepage should load with basic styles thanks to Normalizer and Bootstrap.

    From here on out, the world is your oyster!

    Sage doesn’t give you everything you need for WordPress development but it’s speedy, it’s git-friendly, and it’s modern. I’m not kidding when I say this… the Roots Stack is literally my favorite way to interface with WordPress. Any other way just feels primitive and old.

    It gets even better with deployments and remote provisioning which I will cover in my next post. 

    Further Reading:

    Next: Remote Server Setup with Trellis
  • It’s a pretty loaded term. Web Design… whoof. Let’s dissect this, because it encompasses a very wide range of disciplines. Heres’ just a sampling of what is expected of a typical web designer in no-particular order:

    • Overall Website Styles (style guides, typography, uniformity, continuity, etc.)
    • Wire-framing / Prototyping
    • Components Styles (UI such as forms, headers, buttons, templating, etc.)
    • Website Layout (how do these components fit together?)
    • Writing CSS and Javascript (most, if not all web designers can write CSS)
    • Cross-browser testing
    • Designing / Developing email templates
    • Designing / Developing web banners
    • Animations (CSS, GIF, or even video)

    Crazy right? That’s a lot to ask of one person yeah? Well, that’s what happens when you work with hypertext. What is hypertext? Wikipedia has a great one-liner about what hypertext is.

    Documents that are connected by hyperlinks.

    When your work focus across multiple disciplines via hyperlinked documents — things get complicated. Despite the challenging chaos, it is very rewarding making anything that lives on the web. Be it a webpage, banner or even this post.

    So where do you start as a novice?


    Learn to plan.

    Planning takes many forms. Draw diagrams. Draw blueprints. Sketch out wireframes. Make your drawings as granular or as defined as you like. Do this. Over and over again. Many times. Get comfortable using an eraser. Get comfortable starting over. Learn to plan. Looking to make your first web design project for a portfolio? Some ideas:

    1. Start REALLY small. Design a simple landing page, with a Z-Layout hero. Very common nowadays. Head over to BriefBox for inspiration or ideas.
    2. Don’t know how to draw? Use what you know. Microsoft Word? Pen and paper? Draw on your iPad? Photoshop? Doesn’t matter. Like at all. Just get your blueprint written down for later. More on Tooling below.
    3. Take notes, document your process, and question everything. Can this be simplified further? Will this be on every page? What devices are we planning to see this on? Is the client/brief married to these colors? How will photography be handled?


    Know your tools.

    When your sketch/blueprint design feels like it’s in the right place — it’s time to move your design into production. 

    Literally you’ll be producing a refined visual representations of your design. But what needs to be in this representation? How do you get from your blueprint into production? Most would argue that a Photoshop file is a good document for production. Mainly because you can group layers not unlike components. You can also export artboards as images which is handy for presentations or gathering feedback from clients. I would say, use what you know. I typically use Photoshop or Sketch. Other times I utilize UXPin or InVision as well — which are great for prototyping larger web projects.

    Photoshop is a great go-to tool for designers. Just know that it is rapidly becoming out of date in response to other tools such as Figma and Sketch. Photoshop is a dope photo-editor, but it also produces massive file bloat. Just four artboards filled with assets can be nearly 150mb large if you’re not careful. Also, Photoshop etiquette really is a thing and it doesn’t just apply to Photoshop. Some tips (assuming you’re designing in Photoshop):

    • Watch tutorials on designing in PS
    • Download example files, and starter kits and templates (starting from scratch is ambitious, no need to re-invent the wheel on your first project)
    • Name all your layers properly as components (header, button, footer, main-form, container, etc.)
    • Use high quality assets when possible
    • Design based on viewport max-width, not per device
    • Don’t be destructive. Use linked artwork, icons and photography
    • Hand-off a file that is organized neatly
    • Write a README document that communicates additional design notes (such as hover events or interaction)


    Gathering feedback and refining.

    Once you have your Photoshop file produced and you feel it’s in a good place — take the file, share it and gather feedback. How can it be improved? Refine the edges, add that extra layer of gloss. Iterate your design further. Iteration is a very healthy step in the design process. If you skip this part, it will be painful later on.

    The real truth of design is, no one can tell you what is bad or good (despite the fact many will continue to voice a opinion on what is good or bad). In design, all that really matters is effectiveness. No one cares about your style, your flourishes or your ego in design. An effective design is timeless and useful. Obviously there are trends in design, and from time to time I even indulge in partaking. Just don’t go overboard. Check yourself on trends you see on sites like Behance and Dribbble.


    Move your design into development.

    Development is the stage where your Photoshop artboards are transformed into actual code. A typical web designer should be able to write CSS and HTML. But, not all designers can do that and that’s okay. If writing code isn’t your bag, you can always shop it out to a front-end developer. You may not need a back-end dev for your project but it should be noted the two can be different.

    A front-end developer is a developer who focuses primarily on CSS and front-facing technologies (could be PHP or HTML or even Ruby).

    A back-end developer primarily focuses on server maintenance, provisioning, database management, and more.

    Not all front-end devs have back-end experience, and vice versa. But, some do.

    Pro-tip: Do not waste your time on PSD to HTML companies. The code they produce is awful, not well maintained, and good luck if there’s documentation. Take your time and find the right front-end dev to make you something beautiful. You can for example, hire me. Can’t afford a freelancer? Head to Reddit or even try visiting your local university or junior college. There’s always someone looking to make something cool for their portfolio.

    If you aren’t satisfied with any of those options, you’re left on your own bud. So if you’re looking to learn how to convert your artwork files into CSS / HTML, you’re going to have to take some time off to learn. I’d recommend visitting Codecademy and enroll in a course today! It’s totally free and it’s a great place to find mentors as well.


    Wrapping up

    So all-in-all, your process for getting started in web design looks like this:

    1. Learn to plan, figure out your first web project
    2. Know your tools, produce artwork files
    3. Iterate, improve your design
    4. Get into development, make your artwork come to life (become a CSS master!)



    A few great resources for front-end development:

    1. CSS-TRICKS : probably the best resource for all things CSS and front-end water cooler topics
    2. Codepen : a menagerie of web things
    3. DesignersList : vast resource list of brushes, sites, themes, stock photos, inspiration, etc.
    4. Muzli : Design inspiration, news, and trends.
    5. Hacker News : the pulse of computer science and the web, skeptical vibe and breaking tech news
    6. Reddit – /r/web_design : probably the most annoying place to read about web design

    Some recommendations to follow on Twitter:

    1. @conrfrmn : my personal mentor and friend, web developer at Apple (shoutout thanks for all the late nights hacking and showing me the ropes 🍻 )
    2. @adamselby : another friend of mine, designer and partner at 88oak
    3. @levelsio : creator of and much more
    4. @vanschneider : creator of , and has a dope-as-fuck newsletter
    5. @taramann : designer at @basecamp, and pretty much offers the best comedy relief from #DesignTwitter
    6. @chriscoyier : creator of CSS-TRICKS
    7. @davatron5000 : 1/3 of Paravel, also podcast hosts with Coyier on
    8. @trentwalton : 2/3 of Paravel
    9. @raygunray : 3/3/ Paravel
    10. @paravelinc : the company Dave, Trent and Raegan runs, alway tweeting good things
    11. @sarah_edo : contributor at CSS-TRICKS, Senior Dev Advocate at Microsoft
    12. @brad_frost : web designer, speaker, consultant, cool guy
    13. @littlenono : visual design lead at @ustwo
    14. @smpetrey : the guy that wrote this article, overall good dude, enjoys the web
  • I wrote a new tutorial since this one is a bit out of date.



    Okay so a few things have changed since my April post. I figured I’d write an update on how to get started with Trellis and Bedrock. There has been a ton of commits since then.

    Again, I’m assuming you’re on a Mac and have node, npm, bower and homebrew installed. If not start here. Things are a little different if you’re a Windows user.

    1. Install Git, Ansible and Composer

    brew install git ansible composer

    2. Install VirtualBox

    Install your VirtualBox software and follow the prompts.

    3. Install Vagrant

    Download and install the latest Vagrant.

    4. Starting a Trellis Project, Installing Bedrock and Sage

    By the time we’re done here, you should have a folder structure that looks like the following (taken from the Trellis Repo):      # → Root folder for your project
    ├── trellis/      # → You'ver clone of Trellis
    └── site/         # → A Bedrock-based WordPress site
        └── web/
            ├── app/  # → WordPress content directory (themes, plugins, etc.)
            └── wp/   # → WordPress core (don't touch!)


    1. Creat a Sites directory if you haven’t already and cd ~/SitesFirst, create a new project directory and cd to that directory: mkdir && cd example.comClone Trellis and remove the gitfiles: git clone --depth=1 && rm -rf trellis/.gitClone Bedrock and remove gitfiles: git clone --depth=1 site && rm -rf site/.gitInstall the Ansible Galaxy roles: cd trellis && ansible-galaxy install -r requirements.ymlInstall Sage in your themes directory, and install npm dependencies: cd ../site/web/app/themes composer create-project roots/sage example-theme dev-master && cd example-theme && npm install
      Now, we head back up the tree to Trellis. Here’s the current folder structure there. We need to configure the WordPress sites in group_vars/development/wordpress_sites.yml and in group_vars/development/vault.yml
    ├── trellis/ # → You'ver clone of Trellis
        └── deploy-hooks
        └── group_vars
        └── hosts
        └── lib/trellis
        └── roles

    Here’s an example configuration for group_vars/development/wordpress_sites.yml

          - canonical:
              - # optional redirect
        local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
          enabled: false
          enabled: false
          provider: self-signed
          enabled: false

    Here’s an example configuration for group_vars/development/vault.yml

    # Generate a secure root password
    vault_mysql_root_password: B3LkKUpcZVx4bpLXKXpiez%R
    # Variables to accompany `group_vars/development/wordpress_sites.yml`
    # Note: the site name (``) must match up with the site name in the above file.
        admin_password: admin
          db_password: example_dbpassword


    5. Let’s Take a Break

    Now that the configuration is done, we can begin the real magic. From the trellis directory, we run: vagrant up. Vagrant will ask for your password, and upon pressing enter it will provision a server and get you all setup. It should take about 10–15 minutes to install. So take a breather if you can.

    Luckily Trellis has some pretty verbose error messages and make sure to double check your group_vars if you have any issues. When the dust settles, head to and you should see this:


    Now that we got local development out of the way we can move onto your production setup. It’s all about dev/prod parity nowadays and honestly, it rocks.

    [button type=”success” size=”lg” link=”/blog/remote-server-setup-with-trellis”] Next: Remote Server Setup [/button]