docs for hashtags

#45

activitypub.py

@@ -388,12 +388,13 @@ def postprocess_as2(activity, *, user=None, target=None, create=True):
     # hashtags. Mastodon requires:
     # * type: Hashtag
     # * name starts with #
-    # * href is set to a valid URL (doesn't matter which)
+    # * href is set to a valid, fully qualified URL
     #
-    # If content has an <a> tag with the hashtag name as its text, Mastodon will
-    # rewrite its href to the local instance's search for that hashtag. If
-    # content doesn't have a link for a hashtag, Mastodon won't add one, but the
-    # hashtag will still be indexed in search.
+    # If content has an <a> tag with a fully qualified URL and the hashtag name
+    # (with leading #) as its text, Mastodon will rewrite its href to the local
+    # instance's search for that hashtag. If content doesn't have a link for a
+    # given hashtag, Mastodon won't add one, but that hashtag will still be
+    # indexed in search.
     #
     # https://docs.joinmastodon.org/spec/activitypub/#properties-used
     # https://github.com/snarfed/bridgy-fed/issues/45

templates/docs.html

@@ -48,6 +48,7 @@ Bridgy Fed takes some technical know-how to set up, and there are simpler (but l
 <li><a href="#follow">How do I follow someone?</a></li>
 <li><a href="#unfollow">How do I unfollow someone?</a></li>
 <li><a href="#image">How do I include an image in a post?</a></li>
+<li><a href="#hashtags">How do I use hashtags?</a></li>
 <li><a href="#update">How do I edit an existing post?</a></li>
 <li><a href="#fragment">Can I publish just one part of a page?</a></li>
 <li><a href="#backfeed">How do fediverse replies, likes, and other interactions show up on my site?</a></li>
@@ -327,6 +328,23 @@ I love scotch. Scotchy scotchy scotch.
 </p>
 </li>
 
+<li id="hashtags" class="question">How do I use hashtags?</li>
+<li class="answer">
+<p>Use <code><span class='keyword'>p-category</span></code> and link the hashtag to a fully qualified URL. (Any URL you want!) Fediverse sites like Mastodon will generally rewrite the link to point to a search for that hashtag on the local instance. For example:
+
+<pre>&lt;div class="<span class='keyword'>h-entry</span>"&gt;
+  &lt;p class="<span class='keyword'>e-content</span>"&gt;
+    just setting up my feddr
+    &lt;a href="<span class='value'>https://mysite.com/tag/throwback</span>" class="<span class='keyword'>p-category</span>"&gt;<span class='value'>#throwback</span>&lt;/a&gt;
+  &lt;/p&gt;
+&lt;/div&gt;
+</pre>
+</p>
+
+<p>The leading <code>#</code> character on the hashtag text is optional. If you don't include the hashtag in <code>e-content</code>, or include it but not inside an <code>&lt;a&gt;</code> link, fediverse sites won't add the hashtag text or link themselves, but your post will still be indexed in searches for that hashtag.
+</p>
+</li>
+
 <li id="update" class="question">How do I edit an existing post?</li>
 <li class="answer">
 <p>Edit the post on your web site, then send another webmention to Bridgy Fed for it. Bridgy Fed will refetch the post and send an <a href="https://www.w3.org/TR/activitypub/#update-activity-outbox"><code>Update</code> activity</a> for it to the fediverse.