PageRenderTime 26ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 1ms

/content/posts/2019-10-30-reader-mail-hugo-micropub.md

https://gitlab.com/jamietanna/jvt.me
Markdown | 101 lines | 66 code | 35 blank | 0 comment | 0 complexity | bf96cd45f5844787b0c5b684a0c01cde MD5 | raw file
    

  1. ---
    2. 

  2. title: "Reader Mail: Getting Started with Hugo and Micropub"
    3. 

  3. description: "Answering a question by a reader about how to get started with writing a Micropub endpoint for use with Hugo."
    4. 

  4. tags:
    5. 

  5. - www.jvt.me
    6. 

  6. - micropub
    7. 

  7. - hugo
    8. 

  8. - reader-mail
    9. 

  9. license_code: Apache-2.0
    10. 

  10. license_prose: CC-BY-NC-SA-4.0
    11. 

  11. date: 2019-10-30T21:12:17+0000
    12. 

  12. slug: "reader-mail-hugo-micropub"
    13. 

  13. image: https://media.jvt.me/445ff8a8fc.png
    14. 

  14. ---
    15. 

  15. I received an email yesterday from <span class="h-card"><a class="u-url" href="https://www.barbersmith.com">Ben Barbersmith</a></span>, and with Ben's consent thought I would reply publicly.
    16. 

    17. 

  17. The email in question:
    18. 

  18. 

  19. > Hi Jamie,
    20. 

  20. 

  21. > I've read a ton of your blog posts and hope you don't mind me emailing you!
    22. 

  22. 

  23. > First up, thanks a ton for your posts about IndieWeb. I was completely unaware of this movement until I saw some of your blog posts on lobste.rs, but it seems really cool.
    24. 

  24. 

  25. > I've recently migrated my own site to Hugo ([www.barbersmith.com](https://www.barbersmith.com)), and your posts about the micropub API caught my attention. I'd sorely love to be able to add to my hugo site from a decent mobile client, and micropub seems like the correct solution. You mentioned you had solved the problem already, but I guess the code is very specific to your setup.
    26. 

  26. 

  27. > Any hints or tips for how I might set up a similar solution? I'm familiar with writing and deploying backend services, just wondering if there are any gotchas or words of wisdom you have specifically about implementing the micropub server API, using it to generate hugo files, trigger the site build or auto commit to git.
    28. 

    29. 

  29. > If you do have any code to share, no matter how scrappy, I'd be grateful!
    30. 

    31. 

  31. > Thanks in advance for any time or advice you can provide.
    32. 

  32. 

  33. > All the best, Ben
    34. 

  34. 

  35. A great email, I appreciate you getting in touch and am more than happy to chat more about my work.
    36. 

  36. 

  37. > If you do have any code to share, no matter how scrappy, I'd be grateful!
    38. 

    39. 

  39. Firstly, it turns out that I had not updated my [blog post announcing my Micropub support](/posts/2019/08/26/setting-up-micropub/) to share the underlying source code - woops! That is now addressed.
    40. 

  40. 

  41. My code can be found at [<i class="fa fa-gitlab"></i> jamietanna/www-api](https://gitlab.com/jamietanna/www-api/tree/master/www-api-web/micropub) and is available as Free Software, under the [GNU Affero General Public License v3](https://www.gnu.org/licenses/agpl-3.0.en.html) so please do use it, but remember to abide by the license terms.
    42. 

  42. 

  43. > specific to your setup
    44. 

  44. 

  45. It's true that a lot of this will be specific to the way that I create content, and that my content is made up, but there should be at least some ideas for what to implement yourself.
    46. 

    47. 

  47. > Any hints or tips for how I might set up a similar solution?
    48. 

  48. 

  49. Firstly, I would ask how the site's content is stored? Is it stored in a git repo and put into GitLab.com, GitHub.com, or some other source control offering? Or is it not tracked anywhere?
    50. 

    51. 

  51. Once you know how it's stored, that'll determine what your underlying endpoint will need to work with.
    52. 

  52. 

  53. From what I understand [nanopub](https://indieweb.org/nanopub) will publish to disk, which means that if you're not using source control it's a better fit.
    54. 

  54. 

  55. If you are, you'll need to do some work to make it handle the authentication with their API, and programmatically creating content on your site from the API.
    56. 

    57. 

  57. > any gotchas or words of wisdom you have specifically about implementing the micropub server API
    58. 

  58. 

  59. My daily driver for Micropub interactions is [Indigenous for Android](https://github.com/swentel/indigenous-android), but I also publish content using [MicroPublish.net](https://micropublish.net) and [Quill](https://quill.p3k.io) as well as implementing my own client for my [step counts](/kind/steps/).
    60. 

  60. 

  61. I found that being a well-formed [OAuth2 Resource Server](https://www.oauth.com/oauth2-servers/the-resource-server/) can be a bit of work, and then also being a well-formed IndieAuth Resource Server, too.
    62. 

  62. 

  63. I found that one thing that tripped me up initially was that I didn't support both `x-www-form-urlencoded` and `multipart/form-data` content types.
    64. 

    65. 

  65. > using it to generate hugo files
    66. 

  66. 

  67. For this, I settled on my own JSON structure for a request, which was mapped very closely to the underlying Microformats2 data that the post would contain, with some extra properties for Hugo.
    68. 

  68. 

  69. For instance, this is a like:
    70. 

  70. 

  71. ```json
    72. 

  72. {
    73. 

  73.   "kind" : "likes",
    74. 

  74.   "slug" : "2019/10/3NnXz",
    75. 

  75.   "client_id" : "https://micropublish.net",
    76. 

  76.   "date" : "2019-10-25T19:03:02.264+02:00",
    77. 

  77.   "h" : "h-entry",
    78. 

  78.   "properties" : {
    79. 

  79.     "name" : [ "Like of https://www.reddit.com/r/Eyebleach/comments/dmvrkl/smile_for_the_camera/" ],
    80. 

  80.     "like-of" : [ "https://www.reddit.com/r/Eyebleach/comments/dmvrkl/smile_for_the_camera/" ],
    81. 

  81.     "published" : [ "2019-10-25T19:03:02.264+02:00" ]
    82. 

  82.   }
    83. 

  83. }
    84. 

  84. ```
    85. 

  85. 

  86. I made it a JSON format because then it would be super easy to publish via an API, instead of having to create a mix of YAML/TOML and Markdown.
    87. 

  87. 

  88. > trigger the site build
    89. 

  89. 

  90. For this, because my site is using GitLab CI as its means to build/test/deploy the site, I didn't need to do anything special to get the site building. As soon as the commit arrived on `master`, it would start the process to build + deploy it.
    91. 

    92. 

  92. > auto commit to git.
    93. 

  93. 

  94. For this, I wanted to go API first and interact with GitLab.com's API (as I use GitLab.com for my repo hosting) rather than actually `git commit`ing locally, so I would recommend similar.
    95. 

    96. 

  96. In terms of other recommendations:
    97. 

  97. 

  98. - Read [the spec for Micropub](https://www.w3.org/TR/micropub/) and see if things make sense, if they don't, then [come and chat with the IndieWeb community](https://indieweb.org/discuss)
    99. 

  99. - I would recommend having a "stub" server set up that will allow you to test your Micropub endpoint with a Micropub client, without publishing content, as it'll make it easier to verify things work without testing in production (but it may also be OK if you don't mind)!
    100. 

  100. - Don't worry about implementing all the features, I've only got create functionality via forms, not via JSON, nor things like read/update/delete as I don't have a need yet for all the functionality
    101. 

  101. - Also, don't feel like you need to implement a media endpoint for now, as you may not be publishing anything media-wise!
    102. 

    103.