One of the goals while build­ing the new Mag­num web­site was to low­er the bar­ri­er for con­tribut­ing con­tent. With Git and GitHub it’s al­ready very easy to con­trib­ute code to the project it­self, so why not ex­tend that to the web­site as well?

Guest posts were kicked off with the Area Lights post by Jonathan Hale last week and there are al­ready more ar­ti­cles be­ing pre­pared for the next rounds. Guest posts are about shar­ing suc­cess sto­ries, pre­sent­ing re­search, show­ing pro­duc­tiv­i­ty tricks or, for ex­am­ple, show­ing a deep­er in­sight in­to a fea­ture that was just re­cent­ly in­te­grat­ed in­to Mag­num.

We be­lieve that pub­lish­ing your con­tent here can be ben­e­fi­cial for many sides — for you, as it has the po­ten­tial to reach peo­ple out­side of your usu­al cir­cles, for the com­mu­ni­ty, as fresh and ex­tra­or­di­nary things al­ways spark new in­ter­est, and of course, for Mag­num it­self. Maybe you are work­ing on some­thing cool and don’t have an es­tab­lished place to show it to the world, or maybe you just fin­ished a pa­per about a new ren­der­ing tech­nique and need a place to present a We­bGL de­mo? We’re set up for that.

In­ter­est­ing times ahead.

Be­ing this open to new con­tent would be very hard to achieve with a cen­tral­ized CMS, as po­ten­tial con­trib­u­tors would ei­ther need ac­cess rights or would have to sub­mit a post with no pos­si­bil­i­ty to check the out­put be­fore it gets pub­lished. Here, how­ev­er, you can just build a copy of the whole site on your ma­chine and it­er­ate on the con­tent lo­cal­ly.

Writ­ing a guest post

So, how does one write a guest blog post? First of all, please get in touch so we can make a mu­tu­al agree­ment on the top­ic, scope and time­frame for when it gets pub­lished. The top­ic should in­volve Mag­num in some way, ob­vi­ous­ly.

The con­tent is writ­ten in re­Struc­tured­Text and can be sub­mit­ted via a pull-re­quest to the mosra/mag­num-web­site repos­i­to­ry on GitHub. If you don’t know reST from Sphinx or oth­er doc­u­men­ta­tion sys­tems, the m.css docs have a ba­sic in­tro­duc­tion to writ­ing reST markup. Or you can have a look at source files in the repos­i­to­ry. For ex­am­ple, the whole orig­i­nal con­tent of the Area Lights post is con­tained in the fol­low­ing com­mit: mosra/mag­num-web­site@fd3e­f28

The best way for writ­ing a post is set­ting up a lo­cal copy of the web­site for im­me­di­ate vis­ual feed­back. It’s not strict­ly re­quired, though — you can al­so con­trib­ute the blog post copy sim­ply as a plain text, for ex­am­ple, if that’s a bet­ter al­ter­na­tive for you.

The bor­ing tech­ni­cal de­tails

In or­der to set up a lo­cal copy of the web­site you need Python 3 with Pel­i­can, Pyphen and Pil­low pack­ages in­stalled and op­tion­al­ly some La­TeX dis­tri­bu­tion for math ren­der­ing.

On Arch­Lin­ux it’s the fol­low­ing pack­ages:

sudo pacman -S texlive-most pelican python-pillow
cower -d python-pyphen # Build the python-pyphen package from AUR

On Ubun­tu you need these:

sudo apt install texlive-base texlive-latex-extra texlive-fonts-extra python3-matplotlib graphviz
pip3 install pelican Pyphen Pillow

On Win­dows and mac­OS pick some La­TeX dis­tri­bu­tion and make it avail­able in the PATH. Python pack­ages can be in­stalled via pip3 as well:

pip3 install pelican Pyphen Pillow

Next, make sure to clone the repos­i­to­ry (or your fork of the repos­i­to­ry) in­clud­ing sub­mod­ules so m.css is prop­er­ly in­clud­ed (use git clone --recursive, for ex­am­ple).

That’s it. Now you can build the web­site and start a web­serv­er on http://localhost:8000 with the fol­low­ing com­mand. The web­site is au­to­mat­i­cal­ly re­built on changes in the in­put files.

cd magnum-website
make devserver

By the way…

The last weeks were quite busy with up­dates — in case you didn’t see yet, there is a bunch of new We­bGL ex­am­ples and demos on the Show­case page:

Bullet Physics example screenshot
Bul­let Physics Ex­am­ple wasm we­bgl1 physics
Shows a ro­tat­ing ta­ble full of cubes that you can shoot down.
Object picking example screenshot
Ob­ject Pick­ing Ex­am­ple wasm we­bgl2
Show­cas­es us­age of mul­ti­ple frame­buffer at­tach­ments to im­ple­ment ob­ject pick­ing.
WebVR example screenshot
We­b­VR Ex­am­ple wasm we­bgl1 we­b­vr
A ba­sic demon­stra­tion of how to use the Em­scripten VR API with Mag­num.
Magnum::Ui Gallery screenshot
Mag­num::Ui Gallery wasm we­bgl2 ui
A gallery of var­i­ous wid­gets (but­tons, la­bels, in­puts, modals) pro­vid­ed by the Mag­num::Ui li­brary.