WordPress Conversion: Lessons Learned

It took a while to convert my old static pages hosted in DreamWeaver. There is a lot of benefit to be derived from doing so, but there are things to know. This page summarizes the essential lessons.

Problems with Image Files

In general, WordPress handles images pretty well. In a post, you click [Add Media], which takes you to the Media Library. From there, you can click a thumbnail to use and existing image, or click Upload Images tab to upload a new one.

At times, though, the thumbnail for an uploaded image does not appear in the Media Library. The link to it works, and it appears when you edit it, but for a thumbnail all you get is a gray or black box — and when you insert such image into the post, nothing appears. (If you examine the HTML text, you can see the reference to the image, but nothing shows up in the editor unless you’ve specified a caption or Alt-text (alternative text that appears when the image is absent).

So far, these are the problems I’ve seen:

1. An image with a transparent background.
   Such images do not appear to work in WordPress. However, it is possible that it was actually experiencing problem #2, and that I unknowingly rectified the issue when I re-saved the image with a white background and uploaded it again.
2. A yet-to-be-identified problem.
   Other images like this one do not appear in the Media Library, and do not appear when inserted into a post, even though the link to the image works, and even though it appears when editing the image in the Media Library. (I re-saved that image with a white background and with a different size, but those changes did not fix the problem.)

For Non-Image Files, Create a FILES Subdomain

I had a bunch of text files, spreadsheets, and MP3 files to link to, in the files I converted. In DreamWeaver, that was easy. Just put them in a folder near the article, and access them using a relative link like ../files/someSpreadsheet. But in WordPress, links are absolute — and there is no place to put a raw file.

You can, of course, upload the files to the WordPress Media Library. That works great for images. The images display as large icons, which makes them easy to find a select. But if you have 10 spreadsheets, they all have the same icon. You can read the names, of course, but all those identical icons just muddy up the waters, making it harder to take advantage of the Media Libraries ability to help you find images.

My solution was to create a files subdomain. That turns out to be pretty easy in the CPanel admin system that SiteGround uses. When you create the subdomain, a folder is with that name is created for you in your public_html/ folder.

After that, it was simply a matter of creating a hierarchy under files/ that matched the category hierarchy I created in WordPress. So where /some-category/some-article.html used to reference /some-category/files/some-spreadsheet.xls, that spreadheet now resided in /files/some-category, and the link to it became https://files.yourSite.com/some-category/some-spreadsheet.xls.

Here are the notes I took on the process, and the alternatives I considered:

• The Media Manager is terrific for images, and for a small number of files.
• It will actually handle quite a few file types, but it always displays generic “block” image for a file, which takes up space without telling you anything.
• If you have a large number of files — especially if you have a large number of categories — you need media categories, to make it easier to find things.
• There are a couple of plugins that will let you create categories on media, and they’re free. But to USE those categories, you need to send them money.
• Another way to do it is to create a subdomain for the site. I chose files.treelight.com.
• Creating the subdomain creates a directory (folder) on the server, at /public_html/files.
• FTP can now be used to upload files and retain the folder structure.
• That way, a root-relative link like /essays/images/abc.png can be converted to https://files.yoursite.com/essays/images/abc.png.
• But to keep the folder structure cleaner, I also dispensed with the images/ subdirectory.
• Given root-relative links, you can then do a global regex replace in WordPress to change ="/(.*)/images/ to ="https://files.yoursite.com/$1/

For a New Site, Use Your Local HOSTS File

When your site goes live, you’ll be accessing it with your domain name (www.yourSite.com). But before then, you’ll be accessing it using an “IP” (Internet Protocol) address — a 4-segment number like 123.456.789.256. Translating a domain name into an IP address is what a Domain Name Server (DNS) does — and that’s why you need to set up DNS records to make your site go live.

But until that happens, you use the IP address to access the site. Because until the DNS records are created, yourSite.com doesn’t really exist, as far as the web is concerned.

In DreamWeaver, that’s not a problem. You make all your links relative (either to the site root or to the current file, your choice), and you don’t really care how the site is accessed.So all of your links go to /some-file. 

But in WordPress, all links are absolute links. So links will eventually go to https://yourSite.com/some-post. But those links won’t work right now, so they have to go instead to https://123.456.789.256/~username/some-post, where the numbers are your IP address, and “username” is the Linux username your hosting service saddled you with.

The fact that links are absolute gives you a problem. WordPress makes it spectacularly easy to add a link to another post — that’s one of the features that makes it so attractive. But when you do, the link goes to the URL you used to access the site, and in the initial stages, that means the IP address + username.

In the long term, of course, you want the links to use the site name. Which means that you’ll be doing a big search-and-replace in the database later, to correct them all.

But a bigger problem with IP-address access is that there is no way to access subdomains. So if you created a subdomain for your files, as suggested in the previous section, there is no way to be sure the links work properly until after the site goes live — unless you use the hosts file.

Long after my site was ready to go live (unfortunately), I found out about this capability in a help page at SiteGround (whose technical support is excellent, by the way). The page was How to Use the Hosts File.

Note:
I only found out about because I was wrestling with DNS records (also explained in the previous section). But it should have come up when searching for “how to create a new WordPress site! It would have saved me a lot of trouble!)

On my Windows system, the path was C:\Windows\System32\drivers\etc. (On Linux systems, it’s under /etc. On Mac/OS, it’s under /private/etc.)

All you have to do is add a line to the file that looks like this:

123.456.789.256  yourSite.com  www.yourSite.com  files.yourSite.com


After you do, you clear your browser cache so any pages you previously accessed are reloaded, and Voila! Your system is accessing the site via the domain name, yourSite.com — while to the rest of the world, the domain name still doesn’t exist!

For a New Article, Specify Subcategory ONLY

• If the category is specified as well, the permalink will never contain the subcategory.
• The good news is that when you view that category, all subcategory posts do appear. (It is not necessary to specify the major category in order to see them there.)
• You can specify more than one category or subcategory, but the first one found will always be used as the permalink for that post.
  Note:
  All articles that were created with both category and a subcategory need to be re-created with subcategory only, to get the desired behavior. (So I’m very glad that I put I put off entering everything until I knew more.)

Make Categories Mimic Folders

Folder categories are “clickable”, in that you can adjust the URL for a post or click its breadcrumb entry to see all of the posts in that category.

• Start by displaying categories (and subcategories) in a post’s URL
  Settings > Permalinks > Common Settings > Custom: /%category%/%postname%/
  When a link is generated the %category% pragma expands to the category and subcategory the post is in, so the URLs reflect your intended hierarchy.
• A category sidebar widget that keeps all categories collapsed except for the category of the post your are viewing in would be ideal, but I haven’t found one that works well enough yet.
• Another way is create pages that match your category hierarchy.
• Each page can then have the title you want, and you can either create a manual TOC, or add a “blog element” that lists teasers for the posts in that category. (More on that below.)
• If there are multiple subcategories, there are two choices:
  1. Add a heading element and a blog element for each subcategory, and put a “subcategory menu” across the top of the page.
     • In general, teasers for posts look much better in a two-column format, if they have a “featured image” that displays at the top. The two-column format keeps the images small. In a single column, the images take up most of the page.
     • One way to have a page with multiple categories is to create a row that is divided into multiple columns. Each column then has one subcategory. But if one subcategory has more posts than the one next to it, it leaves a blank area on the page.
     • A better way is to set the blog-element display to the two-column format, rather than the single-column format.
     • Ideally, it should be possible to use the same CSS list-style that the main menu uses, to put the subcategory list at top of page.
  2. Create separate pages for the subcategories, and create links to those pages.
• With your categories set up, you can then turn on breadcrumbs for posts, which displays the categories a post is in (each is clickable).
• You can also create Menu items that match your category hierarchy, using either Category items or the pages, if you created them.
• Changing the category pages would seem to require modifying the WordPress PHP code.
• But that’s never a good idea, because such customizations impede updates. (You have to redo the code change after every update.)
• You can then put a blog element in the page that selects for everything in that category. (Items in subcategories appear.)
• That gives you the same effect as a menu item that goes to that category, but instead of the awkward title, “Archive for the Category: X”, you can create a title you want, like “Essays” or “Golf Articles”.
• Alternatively, you can have multiple blog elements on the page, one for each subcategory.
• In either case, the trick is show readers the possible subcategories, and give readers an easy way to get to them, from that page.
• However, the subcategory TOC would work better as a mini-menu list across the top of the page. Rather than as a vertical TOC.
• The next problem is then the links in any tag cloud or category listings that appear in your sidebar link to the default “Archive of” category pages, instead of to pages you create.

Note:
WordPress does have one unfortunate characteristic in this regard. Many people have tried to explain the issue to them, but as of version 4.7.5, no one seems to have communicated it successfully enough to get it resolved. (The good news is that the issue represents a fairly minor inconvenience, rather than a major problem.)

1. The issue stems from the fact that subcategories aren’t really subcategories. For that reason, they all have to be unique (which is fine).
2. Because they are unique, a subcategory can be accessed in the same way that a category is accessed: https://yourSite.com/subcategory-name. That URL displays all posts in the subcategory, the same way that https://yourSite.com/category-name displays all posts in a category. (That’s not optimal, because it means that things can be accessed without going through the full hierarchy. But it isn’t terrible.)
3. The real problem is that a subcategory cannot be accessed using a URL like https://yourSite.com/category-name/subcategory-name. That URL does not work. So even though your post URL is https://yourSite.com/category-name/subcategory-name/post-title, a user can’t simply chop off the post title to see other articles in that subcategory. They have to know to remove the category name from the URL — all of which represents a small defeat for the hierarchy you were trying to create.

Settings: Appearance > Theme Options > Blog

• Although the title appears smallish, it’s still an H1, which satisfies SEO.
• Custom post-page title should be OFF, so that post title appears in the banner of the page.
• Breadcrumbs
  • Posts page needs to have title “Articles”, “Posts”, or “Blog” to appear with that name in the breadcrumbs.
  • In Appearance > Theme Options > Breadcrumb, the Home Node Name should be blank, so the breadcrumb starts as “Articles / …”

WordPress is NOT a CMS

WordPress does manage content, to a degree, but it has several deficiencies in the area of link management that prevent it from acting as a true Content Management System, or CMS. (DreamWeaver is actually stellar, in that regard.)

The big issue with WordPress is that absolute links are stored. Instead of storing relative links or, better, a database ID in link fields, absolute links are stored that name the site, the category/folder that contains the page, and the page name.

WordPress provides a ton of benefits in the form of SEO optimization, search capabilities, and terrific layouts, but that policy creates a brittle site that requires vigilant link-checking to make sure that site-links and image-links are correct:

• If you move the site, all links in the site need to change.
• If you change the title of a post, existing links are not automatically adjusted.
• If you delete a post, you are not warned of links that will be broken.
• If you change the category a post is in, the link to it will still reflect the original category. (The link will work, but the URL you see will no reflect the optimal path to the post.)

Site-Relative Links Work. File-Relative Links Do Not.

1. • A file relative link (href="foo") from a post in the golf category becomes a link to https://yourSite/foo, which fails.
   • But a root-relative link (href="/golf/foo") works perfectly.
   • The caveat is that it fails while the site is private!
   • At that stage, WordPress is accessed https://yourSiteIPAddress/yourHomeDir/…
     The link to /golf/foo fails in that case, because it becomes https://yourSite/golf/foo, which doesn’t exist.
   • The link will work perfectly when the site has gone public, though, because the golf pages will be reached at https://yourSite/golf.

Convert File-Relative Links Before the Conversion

• Neither DreamWeaver nor WordPress has an option that will change file-relative links like ../images to /essays/images.
• But in DreamWeaver, you can do a folder-by-folder find and replace, to make right change.
• In WordPress, there is no such thing as “folder”, so there is no good way to change to /essays/images in some articles, and /golf/images in others.
• However, that changes only really work for links to files. So a link to a spreadsheet or an image can become an absolute link to your file-storage subdomain, which will save you a ton of grief over uploading to the WordPress Media Library, and then fixing every link on every page.
• Links to other posts will have completely different names. So my Wheat.html article became, in WordPress, “whats-wrong-with-wheat”

Compensate for Name Changes

• The good news is that the longer, hyphen-separated article names are not only more descriptive, they are also search-engine friendly.
• Search engines can parse the title for keywords, and your page ranks higher, because of that.
• The bad news is that any and all links to that page from other sites are now broken — so a page that was once at the top of the search rankings is now at the bottom.
• Before you start, then, it’s a good idea to identify your highest-ranking pages. You can do it manually by searching on the terms your site is known for, or you use a measurement tool like Google Analytics. (Set up an account, identify the “property” (i.e. the website), and then put the code they give you into the pages you want to track.)
• Then, after your site goes public, tell your service provider to set up a permanent redirect, giving the old URL and the new one. So in the example above, /health/nutrition/Wheat.html redirects to /health/nutrition/whats-wrong-with-wheat.
• Consider backing up your old site by setting up a domain for it, and then copying all of the old files to it. (I created classic.treelight.com)
• Finally, modify your 404 Not Found page:
  • Appearance > Editor > 404.php
  • Tell visitors what happened when a link is broken: a) Try searching for it, since the name and possibly it’s location has changed and, b) If all else files, try changing the URL (to classic.treelight.com, in my case).

Standard “Category Archives” vs. Creating a Page for Each Category

To complete the process of mimicking a folder hierarchy, you need a way for readers to click on a “folder”, and see what’s in it. To do that, you have several options:

1. Standard category pages
2. Custom pages with “blog” elements
3. Php hacks
4. [?] Dynamic text-replace plugin (if there is one that will work)

Archive pages provide a of posts in a given category

• [+] You don’t have to do anything to create them.
• [~] The archive for a category like “Golf” automatically includes all posts in subcategories
  (It’s a plus if you want that, a minus if you want the subcategory posts to be separated.)
• [-] They have awkward titles like “Archive for the category: Essays” and “Archive for the category: Golf”, instead of titles that make sense like “Essays” and “Golf Articles”. And you can’t add intro text to those pages.
• Note: The 2-column format for blog rolls keeps “featured images” at the top of the page from taking up too much space when teasers are displayed.

Alternatively, you can manually create a page for each category.

• [+] Pages have the titles you want, and you can add intro text.
• [-] Blog elements don’t have a 2-column format.
  • You can get a similar effect by creating two columns, but then each blog elements needs to display posts in a subcategory.
  • Works well if there are two subcategories.
  • If there are more, then a) You need a menu across the top and b) You get awkward spacing if a subcategory has more posts than the one it is next to.
• [-] In a blog element, selecting a container-category doesn’t automatically include posts in subcategories.
  • One option would be to put a post in both the container-category and the subcategory.
  • However, that post is disliked by search engines (multiple locations for same content).
  • It also hides the subcategories, because users never see them in the URL or the breadcrumbs. (When displayed, a user can easily get to all articles in that subcategory. If not displayed, the user doesn’t even know that the subcategory exists.)
  • Another option is to select all of the subcategories for the blog element (works great, until you change a subcategory name or add a new one).

Hack the Php?

• Lacking a built-in capability, the only way to solve the problem is to hack the Php code that constitutes WordPress.
• Somewhere, there is a generic code that creates the title “Archive for the category:”, and tacks on the category name. That could become a series of if/else-if statements the examines the category name (or slug) and creates the desired title.
• [+] You get the titles you want.
• [-] You have to redo the hack after every update.

Dynamic title replacement?

• Some plugins let you substitute text on a page before a post is displayed.
• That sort of thing could be used for pre-release documentation, to hide the product name until launch.
• At the moment, I don’t if one exists that will change the title of a category-listing
• If one does, it would present a potentially useful solution.

Portfolio Pages vs. Portfolio Elements

1. • There are also “portfolio widgets” you can add to a page, which select portfolio project-pages based on category. (This may be a feature of the Invicta theme I’m using.)
   • Like the blog elements in a page,  the “portfolio” widgets that list portfolio project-pages work differently from the standard portfolio page:
     • The standard portfolio page uses the project-order specified in the project definitions.
     • The portfolio widget doesn’t.

Learn more: Converting to WordPress: Benefits and Drawbacks, Getting Started with WordPress.

Copyright © 2017, TreeLight PenWorks

Please share!