joshuatzwp / joshuatz-wp

Custom WordPress theme for joshuatz.com

---

Instructions

Building

• Vendored assets are bundled using gulp. gulp or npm run build should produce the files, which are checked into git, so they can be pre-built for WP.
  • Currently, this is also dependent on the jPrismToolbar submodule already being installed (see below)

Install

• There is currently no real setup required other than activating the theme
• To use jPrismToolbar, currently you need to use the submodule
  • On initial cloning of the whole repo, you after need to run (once):
    • git submodule init && git submodule update

Page Setup

If you want a homepage, and blog page (e.g. Posts Page), you can set those up by creating blank pages under Pages, and then heading to Settings -> Reading, and setting the pages you created as the static pages to display.

This is also where you can control some related settings, like how many posts show up, per page, on the blog archive / Posts Page

The theme has templates to handle both those pages.

You can read detailed instructions on how to do that here.

Homepage Template

There are multiple homepage templates available. The best way to use one is to manually create a homepage page in Wordpress, assign the template you want, and then under Reading Settings, set the homepage to the static page you created.

This allows you to customize both:

• The template that is used
• Some of the content pulled into the template

Adding a New Page Template

📘 Docs

• Create page under /page-templates
  • Do not prefix with page-, unless you are trying to match to specific slug
• Use multi-line comment to specify:
  • Template Name and (optionally) Template Post Type
  • Good practice: @file to explain in detail
• You can assign the template when editing pages (and posts)

⚠ Be very aware of the WP Template Hierarchy and how it can override settings based on filenames

Optional Settings

• Optional settings:
  • Theme debug logging
    • Logging will only occur if the log file exists. In theme folder, touch config/log.txt. Is gitignored.
  • Theme Settings Page (Dashboard -> Settings -> joshuatz-wp):
    • Google Analytics GA ID - this should be the analytics ID provided by Google Analytics. Should follow format of UA-12345678-01
    • Disqus Custom Subdomain - For if you have Disqus setup and want to enable their comment embed system
  • Custom redirect system
    • You can configure a bunch of pattern based custom redirects with a simple JSON file, rather than having to install a special plugin. Clone jtzwp-custom-redirects.example.json and name as jtzwp-custom-redirects.json and place either in theme directory OR root of WP install - theme will check for both, and take root as preference.
  • Automated post-deployment actions
    • A special URL is available: {website}/deployment-hook/?deploymentkey={secretKey}
      • The secretKey is autogenerated on theme install, but you can manually change/see it in your WP settings
      • Right now, all this does is sets a deployment timestamp used for "cachebusting" static assets
  • "Under Construction" mode
    • You can easily set the site into under-construction mode, which will redirect all non-wp-admins to /under-construction/ for every single page. You don't have to set up the /under-construction/ page to use this feature. To enable, simply define the UNDER_CONSTRUCTION constant to be true (easiest spot is in your wp-config.php file) like so:

      define('UNDER_CONSTRUCTION',true);
      

      • This should be used with extreme caution, as leaving the site in this mode for an extended length of time can have a negative effect on SEO (not to mention a bad user experience).

Recommended plugins and tweaks

• Recommended Plugins
  • Custom Post Type Permalinks - Highly Recommended for my custom post types - WP Plugin Page
  • Yoast SEO - WP Plugin Page
  • Advanced Custom Fields - WP Plugin Page
• Recommended core tweaks
  • Dynamically define WP_SITEURL and WP_HOME in wp-config.php - see this
  • Reduce the number of revisions that wordpress keeps (default is infinity!)

    define( 'WP_POST_REVISIONS', 3);
    

    • Make sure that you put this above

    require_once(ABSPATH . 'wp-settings.php');
    

    • I recommend just putting at top of file
  • Here is a pretty good list of optimizations to make from the default config - link

---

ToDo

• Create mapping system for loading scripts / styles
  • Add SRI attribute support to script queue
• Redo nav and change from hardcoded to more dynamic based on native WP menu
  • Optionally, integrate Materialize walker version
• make /blog a true theme page, rather than have to manually create it
• Add back some sort of lightbox gallery viewer?
• Add back some form of CSS animations (removed wow.js)

---

Dev JS Helpers

Toggle prism toolbars:

function toggle() {
	let _this = this;
	window.showingToolbar = typeof window.showingToolbar === 'undefined' ? true : window.showingToolbar;
	window.showingToolbar = !window.showingToolbar;
	document.querySelectorAll('.jToolbarWrapper').forEach(e => {
		e.style.display = showingToolbar ? 'block' : 'none';
	});
	document.querySelectorAll('pre[class*="language"]').forEach(e => {
		const fn = showingToolbar ? e.classList.remove.bind(e.classList) : e.classList.add.bind(e.classList);
		fn('noToolbar');
	});
}

document.body.insertAdjacentHTML('beforeend',
`
<style>
pre.noToolbar {
	margin-top: 68px;
}
</style>
`
)