Example usage of my HTML to Gemtext API

A few months ago I made an API to do the heavy lifting for the WP2Smol WordPress plugin. The documentation I wrote at the time was pretty sparse and as development on the plugin began in earnest I’ve given the API a good workout and have some example code to share.

The API is basically a POST request to https://html-to-gemtext-or-markdown.p.rapidapi.com/html2gmi/. Options to control how it works are passed as JSON in the body of the request. Standard stuff.

First, construct your JSON for the body of the request:

$body = [
    'html'  => $html,
    'html2md_options' => [
        'strip' => ['b', 'strong', 'em', 'i'],
        'escape_underscores' => false,
        'escape_asterisks' => false
    ],
    'md2gmi_options' => [
        'plain' => true,
        'links' => 'paragraph'
    ]
];

You can just have ‘html’ => ‘<h1>Some html here</h1>’ but I found the results unsatisfactory for all but the simplest HTML.

The API passes the ‘html2md’ options to the underlying python library, documented here. I’m removing bold and italic formatting and changing how underscores and asterisks are parsed to resolve some bugs I noticed in earlier testing.

md2gmi options are similar – they are passed through to the underlying library. Refer to it’s documentation for a full list. I’ve set ‘links’ to paragraph which determines how inline links in markdown are converted to gemtext (which has no inline links).

Send the $body off to the API:

   $body = wp_json_encode( $body );

   $options = [
       'body'        => $body,
       'headers'     => [
           'Content-Type' => 'application/json',
           'X-RapidAPI-Host' => 'html-to-gemtext-or-markdown.p.rapidapi.com',
           'X-RapidAPI-Key' => $api_key,
       ],
       'timeout'     => 60,
       'redirection' => 5,
       'blocking'    => true,
       'httpversion' => '1.0',
       'sslverify'   => false,
       'data_format' => 'body',
   ];

   $response = wp_remote_post( $endpoint, $options );
   if ( is_wp_error( $response ) ) {
      $error_message = $response->get_error_message();
      //@todo display error message
      return '';
   }
   else {
      $response_json = json_decode($response['body']);
      return $response_json->result;      // this is the goods here
   }

This sample code uses WordPress functions to make the request but you could use cURL or whatever. Just set the HTTP headers as shown above.

NB you need a free API key from RapidAPI. Set $api_key to it’s value.

That’s it!