Connecting to WordPress
If you don’t yet have a WordPress site, you’ll need to create one first. Numerous web hosting providers allow you to install WordPress, and many even provide an easy WordPress setup process. There are also dedicated WordPress hosting providers such as wordpress.com where you can create a site in minutes. If you want a local WordPress installation you can tinker with freely, you can even install WordPress on your Mac.
TypeMetal can connect to any WordPress site that supports either the modern REST API or the older XML-RPC API. This includes sites with “myamazingsite.wordpress.com” addresses (the default for wordpress.com accounts), as well as your own custom domains hosted at wordpress.com or elsewhere, depending on the API security settings and authentication method that the site is configured for.
To start using TypeMetal with a WordPress site, you simply provide TypeMetal with the site’s URL and your account credentials, as described below. TypeMetal automatically connects to the server and obtains your site’s content and related resources.
If you have any trouble getting TypeMetal to communicate with your WordPress site, including a possible need for TypeMetal to support a different authentication method, please contact us for help!
TypeMetal currently uses OAuth2 to authenticate communication with wordpress.com-hosted sites.
WordPress sites hosted elsewhere must currently be configured for Basic Authentication — a capability that can be added by installing and configuring a plugin such as this one — in order to use the REST protocol with TypeMetal. (Let us know which authentication method you use — we’re working on adding support for others!) If you’re unable to configure your site for Basic Authentication, you may be able to sync with it by choosing the XML-RPC protocol instead: See “Advanced Settings”, below.
Adding an Account
TypeMetal’s “Blogging” menu lists the WordPress sites that you’ve told TypeMetal about.
To connect TypeMetal to a WordPress site for the first time, choose “Blogging” → “Add WordPress Blog…”.
TypeMetal prompts you to specify the site to connect to and enter your account credentials.
TypeMetal 2.2 features an updated login UI, that’s designed to make basic configuration easier while offering advanced settings when needed. If you’ve used earlier versions of TypeMetal, see below for updated screen shots and instructions.
By default, TypeMetal assumes your site could be at an arbitrary domain hosted anywhere, and presents the following general login UI:
If you’re connecting to a wordpress.com account, choose “wordpress.com” from the “Account Type” popup button at the top of this panel, then enter your wordpress.com user name and password in the fields below that and click the “Login” button. You should be able to connect to a wordpress.com account without any other special settings. When you connect to an account for the first time, wordpress.com will prompt you to re-enter your account credentials and approve TypeMetal’s request in a browser window, as described in “Authenticating With wordpress.com Sites”, below.
For your security, TypeMetal keeps any passwords you enter, together with authentication tokens it receives, in the macOS Keychain. You may delete these keychain items anytime. TypeMetal will prompt you to re-authenticate later, when needed.
If you’re connecting to a WordPress site hosted elsewhere, or potentially your own custom domain hosted by wordpress.com, keep “Other” as the “Account Type”, enter your site’s URL in the “URL” field, then enter your username and password in the fields below.
You can then click “Login” to attempt to connect using REST v2 as the default protocol (this is usually the best choice), or you can click the disclosure triangle next to “Advanced Settings” to see additional options.
Advanced Settings
The expandable “Advanced Settings” area offers additional connection options you can customize:
Protocol
TypeMetal can communicate with your WordPress site using one of three protocols:
- REST v2 is the current standard that most sites should support, and is the recommended setting unless you encounter problems connecting TypeMetal to your site. REST v2 offers the best support for WordPress’ latest features, and will provide the basis for new TypeMetal capabilities in the future.
- REST v1.1 is an older version of the same protocol, provided as a potential compatibility fallback. It is mainly still used by wordpress.com (which also supports the preferred, newer variant, REST v2).
- XML-RPC is the oldest of the three. Its use is discouraged due to weaker security, and many hosting providers disable it by default to protect against security exploits. Use the REST v2 protocol instead whenever possible. XML-RPC support is offered for short-term compatibility with existing WordPress sites.
Rate-Limiting Requests to Your Host
Website security is a tricky business. One way that your WordPress hosting provider may protect your site involves limiting the number of requests allowed from a given source computer (IP address) in some interval of time. When that limit is exceeded, the host may begin denying requests, and may choose to deny all subsequent requests from the originating IP address for a while. These request denials may show up in TypeMetal’s WordPress Sync Log as “HTTP error 418”.
Syncing your site with TypeMetal for the first time, or performing an “exhaustive” sync, necessarily involves a large number of requests, so may can easily afoul of any rate-limiting security measures that your WordPress host has instituted.
If your WordPress host enforces rate-limiting (as is frequently done using the “ModSecurity” Apache server module), you can configure TypeMetal to limit the number of requests it will send to your host over some time interval. You do this by toggling the rate-limiting checkbox on in the WordPress login panel, as shown below.
TypeMetal remembers these settings on a per-project basis. They default to a maximum of 10 requests per 60-second interval (a common setting), but you can change them if necessary to match the limits enforced by your host.
If you encounter trouble syncing your site using TypeMetal that might be due to rate-limiting enforcement, please drop us a note, letting us know which WordPress hosting provider you’re using. The best long-term solution is usually for us to work with your hosting provider to have them “white-list” requests from TypeMetal. The rate-limiting settings in TypeMetal can be useful as a temporary workaround, but will slow down syncing any time the limit is reached. Once a host has white-listed TypeMetal, rate limiting is no longer necessary (and you should disable it to get faster syncs).
These rate-limiting settings affect both REST and XML-RPC communication.
Custom XML-RPC URLs
When communicating with your WordPress site using XML-RPC, TypeMetal assumes the standard WordPress configuration, and attempts to talk to your server at <host>/xmlrpc.php
If your WordPress host is configured to use a different XML-RPC URL, you’ll need to enter that URL in the provided text field, below the “Host” field. TypeMetal will remember the custom URL, and use it every time it syncs with your WordPress site.
If your WordPress host is configured to use HTTPS (secure encrypted) transport, be sure to prefix the URL you type with “https://”.
The “Custom XML-RPC URL” text field is only enabled when XML-RPC is chosen in the “Protocol” popup button.
Authenticating With WordPress.com Sites
When you connect TypeMetal to a wordpress.com account for the first time, a window opens in your default Web browser, prompting you to confirm your account credentials and approve TypeMetal’s request for access to the account’s sites. TypeMetal now requests access to all of a wordpress.com account’s sites at once, so you no longer have to approve access to each site separately as in previous versions of TypeMetal.
Enter your username, password, and any other credentials wordpress.com requests in the automatically opened browser window:
When you authenticate successfully, wordpress.com will prompt you to approve TypeMetal’s request for access to your sites:
Click “Approve” if you agree to authorize the request (or “Deny”, if you change your mind). TypeMetal uses access to your site’s content solely to support your browsing, writing, and publishing needs, and never shares your information for any other purpose. This confirms to wordpress.com that it’s OK for TypeMetal to access your sites’ posts, pages, and associated content. TypeMetal should then proceed to download your content, showing progress as it goes.
TypeMetal’s attempt to connect to your WordPress host should succeed or fail within ten seconds or so. If the attempt fails, you’ll see a result such as “Incorrect username or password” (indicating you may have made a typo entering your user ID or password), or “HTTP error 404” (indicating the host you specified could not be reached — perhaps because you mis-entered the “Host” URL). Review and correct the credentials you entered, and try again.
Troubleshooting WordPress Sync
If you have trouble syncing with a WordPress site, there’s a sync log you can send that will help us diagnose the problem.
To view the sync log for a given account, choose Blogging → View Sync Log from the menus, or click the “Sync Log” button that appears at the bottom of a sync status display for any of the account’s blog windows. The “Sync Log” window that appears contains diagnostic text describing the last few sync sessions, that you can copy and paste. Email it to support@coherencelabs.com with a description of the problem you’re seeing. We’ll do our best to get you up and running again!
If the attempt to connect succeeds, TypeMetal will begin downloading posts, pages, and related information from your WordPress site. Depending on the size of your site, you may need to allow TypeMetal some time to complete this first sync, which downloads all of the site’s content. You’re free to use TypeMetal, and your Mac, for other things while the download continues.
When the sync completes, TypeMetal presents an “Open Blogs” button. Clicking it dismisses the login panel, and opens a blog editor window for each of your account’s blogs (often there will be only one).
Finding Your Blogs Later
Once TypeMetal has connected to your WordPress site, you’ll be able to find your blog(s) listed in the “Blogging” menu. Choose any blog in the list, to have TypeMetal open a window for it.
Removing a Blog from TypeMetal
If you decide you no longer want to work with a given blog using TypeMetal, you can remove it from TypeMetal’s “Blogging” menu.