🚀 ActivityPub Rocks Portal: Technical Discussion

History and Credits

As also mentioned on chat, given the requirement of an accessible dev environment (added to the wiki), I feel that as David already mentions, Haunt imho isn’t fulfilling that requirement.

But I think a proper way forward is to give credit where it is due, both to David and certainly also to @cwebber. A good way to do so is by adding a “History of ActivityPub Rocks” section to the About page, that specifically mentions the way the site was constructed, tech used, and provide a link to the repository for those who are interested. I will update the “Thoughts on Landing Page” I posted yesterday, to reflect that.

Internationalization (i18n)

I feel that - while support for i18n in the SSG is a MUST-have - maintaining actual translations is a nice-to-have. Whether language translations become available depends on community contributions. However, each language that is added is a serious increase to maintenance burden if the expectation is that they stay in sync with content changes in the primary language (English).

The approach taken depends on content strategy. It may well be that the portal only has few content, because it serves mainly to redirect people to appropriate places elsewhere on the web. Support for some of the more dominant languages is also an option, to reach good global coverage (think Spanish, Chinese, French, etc.)

1 Like

Should the Haunt setup be put to bed then indeed such a response would be appropriate.

I would extend it to ensure that the repository should be fully archived on Archive.org (perhaps both as a tar as well as an operable GitLab site).

For example, this is insufficient - as they do not provide content:

https://web.archive.org/web/2/https://gitlab.com/dustyweb/activitypub.rocks/-/blob/master/guix.scm
https://web.archive.org/web/2/https://gitlab.com/dustyweb/activitypub.rocks/-/issues/13

For a technology purporting to be of significant it feels like a major archival oversight.

Anybody got an account to do this?

1 Like

Another related question: We have this vibrant community here. It would be kind of cool, if one could include a “component” that displays recent posts on SocialHub.

Somebody with Discourse experience will probably know if such a component exists.

2 Likes

Actually it’s pretty easy with Discourse to provide a list of topics on a static site, or comments associated to a static page.

Another cool thing is that with Published Pages, we can host markdown-based pages here that can be edited by the community and have them at a stable URL like this one: https://socialhub.activitypub.rocks/pub/fediverse-enhancement-proposals#index

2 Likes

I’ve played around with astro - starlight a bit. I don’t think it can be used for technical documentation without investing a lot of energy. I could neither figure out how to highlight lines of code or insert a “copy to clipboard” button. The instructions, I found only, all involved writing JavaScript and I wasn’t able to get it working (spending a limited amount of time).

However, I think the MDX format is what one wants here. From @how 's first link:

<script src="http://URL/javascripts/embed-topics.js"></script>

<d-topics-list discourse-url="URL" category="1234" per-page="5"></d-topics-list>

This sounds like something that can be turned into an MDX component. I expect similarly a Fediverse integration for Static Sites to come in the form of components.

I think my desire to have this type of integration pretty much forces tools from the JavaScript ecosystem on us. I don’t think using a tool that limits us to be able to do portal well instead of publishing technical documentation is a bad choice.

1 Like

I must say I would certainly prefer something minimalist that does not require JavaScript (i.e., degrades gracefully) and is mostly pre-built at compile time. We can also envision using API calls to Discourse and Codeberg to make things easier.

1 Like

There’s ready-made integrations for the code blocks with some of the functionality you mention. Used for instance on Astro’s docs, see example.

As mentioned this is taken care of in Astra. It does stuff compile-time and generates static output that is published to the site. You can try disabling JS of astro.build or stellar website and it doesn’t degrade. I added “works without JS” to requirements in the wiki.

2 Likes

I do not consider that to satisfy my requirement 3.:

This does not mean that we should not use Astro as a solution, but we should be aware of its limitations. It’s not something that makes building technical documentation painless. Fortunately, we do not want to write technical documentation.

For multiple low-key edition of static pages, I’d really recommend using Discourse’s Published Pages:

  1. Create a ‘web editors’ group
  2. Create a dedicated category for the official site with create-reply-see permissions to the web editors, reply permissions to trusted people, and read-only to everyone else (only the first post makes it to the ‘published page’)
  3. Make the first post (page) a wiki so that everyone in the community can amend the page, or moderate edition like: quote the first post and reply with suggested changes.

The process is transparent, as horizontal as we want it to be, and changes appear straight to the web without having to go through git deployment for selected pages (e.g., the Guide for new ActivityPub implementers works like this and appears at https://socialhub.activitypub.rocks/pub/guide-for-new-activitypub-implementers) — one thing we might want to change is authorship: @nedjo receives notification for every change, and the page fails to reflect the multiple contributors.

You are right. Not the example I inlined. The other integration can be used in plain Markdown docs, but for highlighting and diffs will need something extra:

```sh ins={3,4} del={5,6}
  # Using NPM
  npx astro add @thewebforge/astro-code-blocks
  # Using Yarn
  yarn astro add @thewebforge/astro-code-blocks
  # Using PNPM
  pnpm astro add @thewebforge/astro-code-blocks
` ``

There may be good uses of this for selected sub-pages, but I do not think it can be a whole replacement of a static site generator and the workflow to maintain a site with that? So then this is additional functionality to take into account, once the ssg-based portal is underway.

Note there’s a danger here. If the wiki isn’t the last in the thread no one is aware of edits, and anyone with permission can sneak in malicious URL’s and text.

I’ve been thinking of the sort of tooling that could be used for this, and the idea we could use Fossil came to me.

  1. It supports easily creating and editing pages with Markdown.
  2. It obviously supports revision control, history, diffs, etc.
  3. It has a reasonable degree of a11y (I’m blind and haven’t found obstacles using it).
  4. Does not require javascript.
  5. i18n is more of a question mark, not sure to what extent that’s supported though one could probably do something with it.
  6. Very simple to deploy, replicate and archive.
  7. It gives us a lot of things for free, some of which we might of course not want (forum, real-time chat, issues…).

I realise it’s an unusual solution but I think it could suit this project.

Thank you, and welcome to SocialHub, @modulux. I like Fossil, but would be very hesitant to bring more tools/channels to the mix, as they tend to spread contributors thin and increase maintenance overhead non-linearly. Currently we have repositories under an organization account in the git-based Forgejo forge at https://codeberg.org/fediverse. For instance this is also the place where the FEP process has its home.

1 Like

Indeed I’m promoting this system for selected pages that may be updated by more than just those who can compile the static site.

I think you get notifications of modifications on first-post wikis. Maybe it’s a host-only feature. But as this feature would only be available to an editors team, I see no danger here. People with no permission to edit the first post can still suggest changes by replying to the topic.

That’s an interesting proposition, and I’ve been looking into it for a while, it remains something of a niche although I really appreciate the integration of issue tracking and so on within the system. But as @aschrijver mentioned, we’re kind of bound to Git these days. (I know some developers prefer Mercurial, but the vast majority adopted Git, and Codeberg primarily uses Git.)

As a matter of curiosity, how do you fare with Git with regard to blindness?
And do you have specific preferences for static site generators that are more accessible than others?

I think what we need is some way to spit out HTML pages and eventually grab live information at compile time from Forgejo (Codeberg) and Discourse (SocialHub) APIs to generate indices for FEPs, open issues and discussions, and so on. The process would mostly be automated and the site rebuilt whenever a change is made to either information sources, or on-demand, maybe via order in a Matrix room, or post to a bot on the Fediverse, or run manually. Many of the informational pages should be editable straight from the SocialHub to leave space for both automation and flexibility.

A quick look at the repositories on the Codeberg Fediverse shows that Hexo and Jekyll are used. I know everyone would like their own pet static site generator there, but we should focus on Markdown integration (since we’re using it everywhere)… @aschrijver proposed to settle on Astro which seems to be a good option with native support for Markdown.

Hi,

That’s an interesting proposition, and I’ve been looking into it for a while, it remains something of a niche although I really appreciate the integration of issue tracking and so on within the system. But as @aschrijver mentioned, we’re kind of bound to Git these
days.

Understandable. I don’t especially like it but the consensus is there among the vast majority of devs.

As a matter of curiosity, how do you fare with Git with regard to blindness?

Git itself is fine–other than issues that are largely unrelated to blindness. There can be some problem with the web interface to repos (github, gitlab, and company). In that regard, it varies.

And do you have specific preferences for static site generators that are more accessible than others?

I’d say that depends a lot on the themes used. I have experience with Pelican as an example of a site generator that produces accessible results. Incidentally it has fair support for i18n as well.

2 Likes

I think we should take A11y into account seriously. This is part of the Fediverse etiquette to take time and make alternative text available for pictures, so I suggest we take the same care for revamping the ActivityPub-related sites.

You’re welcome to steer this work in the right direction @modulux since you may see things we cannot.

2 Likes

Wholly agree. The summary wiki already contains few notes for that requirement.

1 Like

Just got a message from Christine Lemmer-Webber from the same thread:

I’d love to see ap.rocks maintained in its Haunt form. I’m not so sure
we’re going to see it happen. It’s more important that it continues and
survives I suppose, ultimately… and the people maintaining it will
have to make the decisions on what tools they want to use.

But I will hands-down say that Haunt was an EXCELLENT environment for
writing ap.rocks. The implementation guide page especially is a great
demonstration of Haunt’s power:

ActivityPub Rocks!

Check out reports.scm:

www/reports.scm · master · Christine Lemmer-Webber / activitypub.rocks · GitLab

Pretty cool, yeah? Well, I thought so… I can’t imagine doing anything
like that as easily in any of the other static site generators I’ve
used.

Which was autogenerated from reports that used the AP test suite (also
Guile based, and sadly long down… though someone’s been working on
reviving (and rewriting) it…)

Haunt treats a website as a program and its output as evaluating that
program. That combined with sxml is a really cool environment. Most of
the rest of the world hasn’t realized as such I guess. Oh well…

https://mail.gnu.org/archive/html/guix-devel/2023-09/msg00546.html

1 Like

and just to point out:

when I made suggestions for me to manage and fumble using Haunt, that I had already looked under the hood and examined such content publishing mechanics.

A post was split to a new topic: Help wanted with unverified forum member account

I think we need to make it clear that this does not depend on a domain name where we have no control of. I’ve been asking @cwebber for DNS configuration control over this domain for a long time, and every time I have met silence.

The issue I have put forth is that if we have a website on a domain, and email on another, then Gaggle will refuse to deliver email, plain and simple. If you are a GMail user, you probably did not receive any notification from this forum in a couple of months.

@dansup has a number of nice domains that could be used instead of activitypub.rocks if @cwebber keeps failing to take a long-term decision about community governance. This is why I want us all to think about establishing a non-profit.