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.)
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.
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:
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.
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.
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.
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:
Create a āweb editorsā group
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ā)
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.
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.
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.
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)ā¦ @aschrijverproposed to settle on Astro which seems to be a good option with native support for Markdown.
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.
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.
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:
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ā¦
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.
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.