Blog Writing

Okay this isn't wiki editing but still a relevant, community-driven aspect of Batocera. This is going to be a very personal, subjective article on the things I've learned wrangling the Flarum forum tools to make presentable blog posts.

When you first open up a new blog post to write you'll note that it's pretty empty.

Click on the Update blog settings button to add a banner image, title summary and to make it a highlighted post or not! I only highlight major release blog posts and recommend you do the same.

I've uploaded some logo splashes that make for appriopriate banners (click to get their URLs!):

Of course, a screenshot demonstrating a major addition or change would be preferred!

Then you can assign it an appropriate category and title by clicking the respective text:

Flarum uses a custom version of Markdown syntax, so any formatting code should be similar. But what's the custom part? Stuff like spoilers, auto-embedding and margins. Here's some basic code I've learned:

### Header title
**Bold text**
_Italicized text (also_supports_underscores)_
>Quoted text


>!Hidden text

[Display text](batocera.org "Text to describe what it links to.")
- First item in a bullet list
- Second item in a bullet list


1. First item in a numbered list
2. Second item in a numbered list

which would appear like so:

Good practices:

• Header titles per topic
• Bold text whenever mentioning an emulator name
• Italicized text for additional notes/edits
• Hidden text for superfluous details/accessibility
• Bullet lists for listing all the added emulators (with specific platform support in parenthesis)
• Numbered lists for directions.

Here's an example:

The extra lines after the quoted text, hidden text and bullet list are required to not have the following text also be included in it. You can also use hidden text to hide embedded media until the user clicks on it. Speaking of…

The Flarum blog by default uses a width that is 655 pixels wide, shrinking down to 547 on smaller screens. Keep this in mind when creating media to embed for the best efficiency. Most image programs allow you to use bicubic resampling, which offers the best quality when shrinking an image down. Of course, for images Flarum will automatically resize the image for you.

It will not do so for videos. Videos whose frames are larger than 655 pixels in width will be cut off, so resizing is required.

If you're using ffmpeg to encode/convert your video, here's the command I use for widescreen videos:

ffmpeg -i "inputfile.mov" -s 655x368 "outputfile.webm"

For 4:3 videos you should use a resolution of 655×491 instead.

You can drag and drop the files into your command prompt to save having to type out the entire path. Any video file format can be the input, but I recommend .webm for the output as that works on most browsers/devices (except iPhones, update the backend Apple!) To switch formats, just change the extension.

There is a way to upload media files directly to Batocera's servers, but I haven't figured it out/been given permission to do so. I've been using this Wiki's Media manager (the one you get to by clicking the “Add images” button in the edit page) to upload files for the blog, it works surprisingly well. Click on the “blog” section on the left and upload your files, then click “Done”. They'll appear at the top of the list. You can click the magnifying glass to get a URL that goes directly to the file, this is what we'll be using to embed media into the blog post.

Once you've got your video and uploaded it to the wiki, grab its URL and embed it like so:

![Alt-text](link-to-image-to-embed "Pop-up text")

Alt-text should be used for accessibility (explain what happens in the video), as that's what will load if the video fails to load or the user is using a screen-reader. The pop-up text will appear when the user hovers their mouse over it, make sure to put a really good joke or a snarky comment here. For example:

![Picture of the Capcom Home Arcade.](https://wiki.batocera.org/_media/hardware:cha-case-front-thumb.png "It's literally a giant Capcom logo.")

which appears like so:

To embed videos, just paste in their URL like so:

>!Alt text
https://wiki.batocera.org/_media/blog:capture-2021.09.03-06h32.04.webm

which embeds the video with some pretty video controls and a big play button:

You clicked that, didn't you?

Just note that unlike images (that will be scaled down for you), large videos will be cut off. Refer to above on how to prepare your videos.

In the case that you'd like to use your own thumbnails instead of the one generated from the video file, you can use the following instead:

[![Alt-text](thumbnail-URL)](video-URL "Pop-up text")

Here are some templates for play buttons to super-impose on video thumbnails (click to get their original res):

Just like with videos you can easily enough just have a direct link to an audio file to have a preview of it appear:

But unfortunately it looks kinda garbage without any image to accompany it. You'd think the obvious solution would be to embed the album art into the audio file via its ID3 tag, but you see Flarum was developed in the stone ages, where embedded album art was but a fart in the wind of id specifications.

We can work around this by encoding a video with the audio copied over. In order to save space, I use a framerate of one frame per ten seconds and a low-quality CRF of 38. If you're using ffmpeg, here's the command:

ffmpeg -loop 1 -i "thumbnail.png" -i "songfile.ogg" -r 0.1 -s 270x270 -crf 38 -shortest -acodec copy "output.webm"

I use such a small resolution because it looks nicer and the blog can use the smaller 547 margin without cutting off anything.

Now it looks much nicer: