HaxeFlixel site not running locally. Should we replace docpad?

[RichardBray]

I've been thinking about improving and adding some content to the blog page, maybe creating a community page. I heard it's difficult to get the site up and running locally so, as a full-time web dev I rose to the challenge and have managed to get it working, mostly:

There are two things I haven't been able to figure out.

1. Why the docpad thumbnail plugin doesn't create thumbnails

Lies!!! Thumbnail generation did not complete, see:

2. Why the running docpad run doesn't bring up the server

So far so good:

Where is the site 🤷‍♀️

I've had to get around this by just building the site and using the http-server package

---

Thoughts

Docpad is pretty old (I mean, who writes coffeescript nowadays), and although we could fix these specific issues with the site, it would be better to move onto a more popular and stable static site generation tool.

But this is all my opinion, it would be good to get the thoughts of others.

[Stilic]

Yeah, I agree with that. Maybe I will get some time to do that...

[RichardBray]

Yeah, I agree with that. Maybe I will get some time to do that...

Nice, thanks for your help. I think it would also be good to get buy-in from people who can merge code to the repo then we can discuss the best tools/packages to use.

[Geokureli]

this web dev stuff is pretty over my head, if you think it's a good idea and got some time to implement then I say go for it

[RichardBray]

Nice okay, I'll see what I can rustle up. I'll mess around with Gatsby for this. I've heard good things about it. @Stilic I don't know if you have any other tools in mind.

[Stilic]

Nice okay, I'll see what I can rustle up. I'll mess around with Gatsby for this. I've heard good things about it. @Stilic I don't know if you have any other tools in mind.

I use Svelte for my website actually. I think we can make something like a documentation generator using it. (there is already something like that also)

[RichardBray]

I use Svelte for my website actually. I think we can make something like a documentation generator using it. (there is already something like that also)

Ah Svelte is a good shout. I don't have a lot of experience with it although I've heard good things.

For static site generation, I think SvelteKit might have to be used. The docs plugin link you provided looks like it's depreciated.

Ideally, I think something that is easy for people not familiar with web technologies to edit and add to. I don't know if SvelteKit supports markdown, I'm sure it does, but it would be something to look into.

I think the next step from here would be to build a little site in SvelteKit and figure out if it's easy for others to add pages to and easy to deploy. If you're happy to do that @Stilic that would be great, but no worries if not.

[Stilic]

I use Svelte for my website actually. I think we can make something like a documentation generator using it. (there is already something like that also)

Ah Svelte is a good shout. I don't have a lot of experience with it although I've heard good things.

For static site generation, I think SvelteKit might have to be used. The docs plugin link you provided looks like it's depreciated.

Ideally, I think something that is easy for people not familiar with web technologies to edit and add to. I don't know if SvelteKit supports markdown, I'm sure it does, but it would be something to look into.

I think the next step from here would be to build a little site in SvelteKit and figure out if it's easy for others to add pages to and easy to deploy. If you're happy to do that @Stilic that would be great, but no worries if not.

I don't have much time to do that now, but I can see if I can do it later.

[RichardBray]

Cool beans. I'm moving house (as you'll find out soon if you regularly watch my videos), so I might not get round to this until around May/June ish but I'll ask around the community for help once I start.

[Geokureli]

take your time, guys, appreciate people looking into this

[Stilic]

Going to start that soon since I can now.

[RichardBray]

Going to start that soon since I can now.

Nice, let me know how you get on 👍

[gamedevsam]

@RichardBray I recommend going with Next.js if you're looking to re-write. It's built on top of React and has an unrivaled development experience.

[RichardBray]

@gamedevsam yeah I'm more of a React dev myself but I want to go with something that the open-source community will feel the most comfortable with contributing to. If that happens to be Next.js then so be it.

[gamedevsam]

Outside of plain vanilla JS, React has pretty much won the front end framework battle. Next.js includes a bunch of extra utilities and has an opinionated project structure that eliminates a lot of decisions you'd otherwise need to make. It also has support for static site generation, so it's a good option to convert markdown into distinct webpages for example. A full re-write of the site seems really ambitious to me, but honestly if we don't modernize it, it's likely to never get any significant updates.

I used this Next.js repo as an inspiration for my own site, it has a lot of goodies and best practices, might be a good place to start: https://github.com/leerob/leerob.io

[gamedevsam]

@Stilic if you've already started a Svelte implementation, don't let me stop you :-P

Everyone is going to have their favorite framework, it's just the nature of the ecosystem at the moment.

If you're open to the idea I still encourage you and Richard to look into Next.js since it really does simplify a lot of things for you (and it has amazing docs, which is really important).

PS: I checked out your website, you should check out Zorin OS if you're looking for a sweet Linux distro ;) PPS: Before messing with dual booting linux, you should really have a Macrium Reflect Rescue USB - it will help you restore the windows boot loader to a good state in case something goes wrong.

PM me on Twitter if you want to connect on Discord or something: https://twitter.com/gamedevsam

[Stilic]

@Stilic if you've already started a Svelte implementation, don't let me stop you :-P

Everyone is going to have their favorite framework, it's just the nature of the ecosystem at the moment.

If you're open to the idea I still encourage you and Richard to look into Next.js since it really does simplify a lot of things for you (and it has amazing docs, which is really important).

PS: I checked out your website, you should check out Zorin OS if you're looking for a sweet Linux distro ;) PPS: Before messing with dual booting linux, you should really have a Macrium Reflect Rescue USB - it will help you restore the windows boot loader to a good state in case something goes wrong.

PM me on Twitter if you want to connect on Discord or something: https://twitter.com/gamedevsam

I already used React in the past, for some hobby projects. But I am OK to use Next!

By the way, thanks for the suggestion!

[ninjamuffin99]

haxeflixel website we write it in haxe 🤝 https://github.com/massive-oss/haxe-react https://github.com/MVCoconut/coconut.ui

[RichardBray]

haxeflixel website we write it in haxe 🤝 https://github.com/massive-oss/haxe-react https://github.com/MVCoconut/coconut.ui

As cool as that would be I don't know if it's a route we want to go down.

Based on what Sam suggested NextJS would be the react framework of choice for this re-write and we're hoping to go down the static-site generation route. NextJS is quite well maintained for JS/TS so I have faith that will be around for the next 5 years (no pun intended).

However, I'm not sure about the Haxe + React support will be around that long, let alone the support for NextJS in Haxe. Also when it comes to doing things like writing markdown in NextJS, I don't know if the plugins for that will be supported in Haxe and if this is something that needs to be done myself dts2hx style myself each time there is a package update I don't know how maintainable that is.

But this is something I haven't tried before and maybe it's super simple 🤷

[Stilic]

haxeflixel website we write it in haxe 🤝 https://github.com/massive-oss/haxe-react https://github.com/MVCoconut/coconut.ui

As cool as that would be I don't know if it's a route we want to go down.

Based on what Sam suggested NextJS would be the react framework of choice for this re-write and we're hoping to go down the static-site generation route. NextJS is quite well maintained for JS/TS so I have faith that will be around for the next 5 years (no pun intended).

However, I'm not sure about the Haxe + React support will be around that long, let alone the support for NextJS in Haxe. Also when it comes to doing things like writing markdown in NextJS, I don't know if the plugins for that will be supported in Haxe and if this is something that needs to be done myself dts2hx style myself each time there is a package update I don't know how maintainable that is.

But this is something I haven't tried before and maybe it's super simple 🤷

The idea of using NextJS is good, but with Haxe, I don't see what it adds...

[Geokureli]

The idea of using NextJS is good, but with Haxe, I don't see what it adds...

I believe the thought was that a site written in Haxe would be more accessible to HaxeFlixel contributors who want to add to the site. I'm all for enabling contributors, but if the tech stack isn't stable we'll be having the same problem in no time

[gamedevsam]

Not to mention you'd just add complexity to the stack, keep things simple.

[RichardBray]

Hey all, I know there hasn't been much movement on this and I hope to get started around October this year but I just want to run a few things past you all technology wise before work begins.

Technology wise here's what I'm thinking

• Node 18
• NextJS (Static Site Generation)
• Typescript
• CSS Modules
• Conventional commits
• Deployment via Github actions to Github pages for dev site

---

I'm thinking of doing a little proof of concept repo to share with you all so you kind of know what to expect. Also so I can check if it's possible to do static site generation with React server components in NextJS 😁

Also, is everyone happy for a new repo to be created for this or should everything be kept in this repo but just on a different branch?

[Stilic]

Hey all, I know there hasn't been much movement on this and I hope to get started around October this year but I just want to run a few things past you all technology wise before work begins.

Technology wise here's what I'm thinking

• Node 18
• NextJS (Static Site Generation)
• Typescript
• CSS Modules
• Conventional commits
• Deployment via Github actions to Github pages for dev site

I'm thinking of doing a little proof of concept repo to share with you all so you kind of know what to expect. Also so I can check if it's possible to do static site generation with React server components in NextJS 😁

Also, is everyone happy for a new repo to be created for this or should everything be kept in this repo but just on a different branch?

Maybe create a new repo? Also can we use the latest LTS release of Node instead of Node 18?

[RichardBray]

Cool, we can do that. I think once Node 18 becomes LTS it shouldn't be too difficult to upgrade the dependencies.

[RichardBray]

Hey all, I've started the rebuild of the HaxeFlixel site and you can see my code here https://github.com/RichardBray/hf-site

@Stilic I've already added you as a collaborator. I'm also streaming my progress on YT if you're interested https://www.youtube.com/watch?v=Qz7eAafAgKo&t=2560s

[Stilic]

Hey all, I've started the rebuild of the HaxeFlixel site and you can see my code here https://github.com/RichardBray/hf-site

@Stilic I've already added you as a collaborator. I'm also streaming my progress on YT if you're interested https://www.youtube.com/watch?v=Qz7eAafAgKo&t=2560s

Good!

[SeiferTim]

Hey all, I've started the rebuild of the HaxeFlixel site and you can see my code here https://github.com/RichardBray/hf-site

The concern I have (and I think a few people touched on it above) is: how easy would it be for someone to change or add to the site?

One of the issues with the current site is that things got out of date and 'broken' to the point where no one was sure how to make simple changes to the site. Also, and it's a problem with snippers.haxeflixel.com as well, you have to download and install a bunch of stuff that maybe someone isn't super-familiar with just to submit something simple...

Is there a way that the core site could be configured so that someone with limited experience could contribute with ease?

Specifically: Demos, Showcase, and Tutorials If there was a super-easy method that someone who wanted to add to one of these sections could just commit just a new file in a special Markdown format or something...

I'm familiar with Jekyll, and I've used Hugo a bit, but for something where I might personally only be contributing something tiny once every couple of years it feels bad to have to spend 45m downloading, installing, setting up, and refamiliarizing myself with how the site even works when all I want to do is add a picture and a link to a URL...

I think I'm picturing something as 'simple' as what Haxe.io is doing? I just don't know how to set that up.

Also: could the HaxeFlixel site have something similar to that? a weekly/monthly list of news/releases/info?

[gamedevsam]

Next.js is a solid production ready framework for web dev, standing up a local instance of the new site is as easy as running npm install and npm run dev. We can probably use markdown or JSON files to add demos, showcases and tutorials, which case adding content to the site would be super easy. Not sure what @RichardBray is planning to do for the content sections of the site atm.

[Geokureli]

I was under the impression we would keep the existing markdown demos and snippets. I agree it's important that haxe developers should be able contribute content to the site without much webdev knowledge.

[RichardBray]

Yeah I'll definitely try and keep as much of the old markdown files as I can. I plan to add a lot of documentation, maybe even some videos on how to do those things.

[Geokureli]

@RichardBray @gamedevsam @Stilic this seems like as good a place as any to mention that I have no idea how to deploy site changes to haxeflixel.com. I've tried running several github actions on all the various flixel repos but still FlxRandom's header comment does not match what is on master.

we have a lot of breaking changes coming in the next release and I want to update the documentation accordingly

[gamedevsam]

Fairly sure the only people that know are @Gama11 and / or @impaler.

[Gama11]

Changes to haxeflixel.com are deployed by CI on the master branch of this repo. Changes to docs.haxeflixel.com are deployed by CI on the master branch of this flixel-docs. However, it uses the latest Haxelib release of Flixel for this: https://github.com/HaxeFlixel/flixel-docs/blob/master/.github/workflows/main.yml#L18

Otherwise you could not make changes to https://haxeflixel.com/documentation/ without accidentally deploying the dev branch API docs.

[Geokureli]

However, it uses the latest Haxelib release of Flixel for this

looking at the latest FlxRandom.hx on haxelib this appears to match the current docs on the api page. the reason that master is different is because I (likely erroneously) committed that specific change directly to master, instead of dev, and there has been no haxelib release since then.

Thanks for the info!

[Gama11]

Ah, yes, IIRC setup-flixel doesn't know anything about Haxelib releases and just assumes that the master branch contains the latest Haxelib release.

[Geokureli]

Ah, yes, IIRC setup-flixel doesn't know anything about Haxelib releases and just assumes that the master branch contains the latest Haxelib release.

Wait so then is it checking the master branch or the latest haxelib? the latter would make sense based on what I'm seeing, but it sounds like it's the former

[Gama11]

You're right, I misremembered. It installs from Haxelib. https://github.com/HaxeFlixel/setup-flixel/blob/master/src/Main.hx#L123-L128

[RichardBray]

Hey all. Just want to give an update on the development of the new HaxeFlixel site.

Here is the link to the repo (https://github.com/RichardBray/hf-site) and here is the site so far https://hf-site.vercel.app/

I'd say it's about 50% done. Here is what is outstanding.

1. Content for the Docs

This by far is the biggest blocker for me. It looks like all the content exists on this github repo https://github.com/HaxeFlixel/flixel-docs and I'm not sure how the current site pulls it as all the other information exists in markdown files local to the project. Is there a script that pulls that repo down and renders that?

2. Deployment

The current site is deployed onto github pages. I tried to do that for the new site but it was built in NextJS 13. It's very difficult to find information on how to deploy a Next 13 site even on the official documentation https://beta.nextjs.org/docs. So I've deployed it to Vercel for now. Hopefully that information will be released soon.

3. Rendering code snippets

If we compare this page on the new site (https://hf-site.vercel.app/blog/13-HaxeFlixel-DragonBones-Support) to the same page on the old site (https://haxeflixel.com/blog/13-HaxeFlixel-DragonBones-Support/) you'll see the code snippets are rendered differently. I've tried to find the library that was used to render the code on the old site but haven't been able to find it. I'm thinking of using prism.js but I just wanted to ask here in case anyone know what that library is.

4. Disqus

You'll notice the blog on the current (old) site allows people to add comments via disqus which I think is broken right now. Is this something we want to keep for the new site?

5. The fundraiser blog post

What is the deal with that (https://haxeflixel.com/blog/05-fundraiser/). Every other blog post is in mark down and this one is in html or html.eco. In my head it's not a blog post and should be it's own page all together if it has this much custom content. But I just wanted to get your view on it. Also, where does the fundraiser data come from?

6. Small bits

There are some missing images on the demos page (this works fine locally). Some errors in the console (mainly to do with React server components), which I think can be fixed by making the HTML/JSX more semantic. Missing search bar at the top (should we even keep this?). And a few bits of small CSS tweaks here and there. Also the 404 page.

Basically, I will get to these things eventually but things would most likely get done faster if I got some help. So please feel free to reach out to me or just submit a pull request to the repo with the fixes.

As usual, I'm happy to answer questions anyone has and suggestions to the codebase. I'd like to make it as contributor friendly as possible 💪

[impaler]

Hi @RichardBray nice work on porting this old website to something more "modern". Docpad was one of the "popular thing" around 9 years ago when I did this, it may have actually been before React was released and Vercel didn't even exist lol :)

Dont have much free time to offer implementation help, but here is my feedback on your issues, hope this helps:

1. I believe the magic for the handling of the docs repo is a docpad plugin called repocloner here https://github.com/HaxeFlixel/haxeflixel.com/blob/dev/docpad.coffee#L211. So you would either need to implement some feature parity with that eg maybe a git submodule or pre build script to fetch that data. Another option is to also just merge that content in with the site, but that would looks all the history of the repo if thats important to anyone.

2. I could be wrong but I dont think you cant host NextJS SSR on github pages if thats what you are trying to do? AFAIK github pages is designed for static websites like this docpad was. I think when you use next you need to use the less documented export feature to do the same, there maybe some limitations vs node as a backend vs static eg https://nextjs.org/docs/advanced-features/static-html-export#next-export

3. Yeah its not obvious what highligher is configured here, just see the theme here https://github.com/HaxeFlixel/haxeflixel.com/blob/a6c78105e26a1f897e470f4ceb8f0f9a729b813c/src/documents/styles/highlighting.less#L19. This is 9 years ago so there probably going to be better solution for highlighting and if you are now using React probably something more suitable.

4. I think a link to the github hosted discussions would be a good alternative solution, there have been so may versions of the forum over the years and seems like microsoft managing that now is great solution

5. That data is from a scraper I wrote a long time ago https://github.com/impaler/indiegogo-backers sorry dont have the raw data from that anymore and that scraper would probably need updating. I think it would be easier to just scrape the current html to what you want.

Cheers.

[Gama11]

Syntax highlighting is actually a post-processing step nowadays that runs over the generated output, using the highlighting engine behind VSCode: https://github.com/HaxeFlixel/haxeflixel.com/blob/dev/.github/workflows/main.yml#L22-L28

[gamedevsam]

@impaler

2. You absolutely can, with the export functionality.

@RichardBray

5. We should create a list somewhere (maybe one of those new github projects) and add this page to it, and others that don't convert well.

PSA:

You need to avoid using getServerSideProps and any other server functionality, to ensure this website is basically a bunch of static files.

I've seen uses of generateStaticParams in the codebase, which is a feature of Server Components, a beta feature in Next.js.

Instead, you should leverage getStaticProps and make sure all of the pages in the codebase are generated at build time.

[gamedevsam]

@RichardBray any progress on this? I'm interested in using HF funds as a bounty to see this work completed.

I believe not being able to iterate on the docs website is a significant problem for the HF community going forward, and as the Patreon treasurer I have some funds at my disposal to incentivize the completion of the work.

I'm willing to put a bounty of $500 to complete the development of the website, and an additional $250 when it's deployed and finally replaces the current docs website (you'll likely need @impaler's help for this).

As for your questions, I'm not the final authority on this (I'd like to hear from @Gama11 & @Geokureli since they have been the core maintainers for a long time), but I can answer you from the perspective of treasurer, and give you some idea of the "acceptance criteria" for unlocking the bounty:

1. Content for the Docs

My advice here is to clone the flixel-docs at build time, and use a mix of getStaticProps & getStaticPaths to build them into final HTML pages that can be statically hosted (make sure to configure Next.js for static export, more info here).

2. Deployment

If you configure Next.js for static export), this will be a non-issue.

3. Rendering code snippets

I'd say just use whatever works with the least amount of effort. We can always improve it later if we find a better alternative.

4. Disqus

My recommendation is to just kill this feature for the new site. Again we can always revisit this later. The big problem now is that the site cannot be updated, and is frozen in time. We need to address this issue first, then we can make improvements if we want to.

5. The fundraiser blog post

I recommend just recreating this in Markdown, preserve the indiegogo backers by displaying them in a bulleted list or table, ex:

• Blue Bottle Games, LLC ($1000)
• Solar Powered Games , e.K. ($500)
• etc...

6. Small bits

If an issue is bad enough that you think it needs to be fixed before shipping, fix it, and if you need help, reach out to me directly on twitter. Don't think anyone else will have time to do the actual work, but I can definitely answer questions and even hop on a call and do some pair programming / debugging on occasion (if I'm not in a meeting that is... so many meetings).

I'm open to answering any Next.js related questions you may have, hit me up on twitter anytime.

[RichardBray]

Hey all, yep I'm still here but haven't look at the site in a while :(

Although the idea of a bounty is interesting 😁

I think the Next.js site so far (https://hf-site.vercel.app/) is good enough to be on something like beta.haxeflixel.com for people to mess about with and give their thoughts.

Also I think at the time I was building the site, Next.js 13 was very new and there wasn't a lot of documentation about it. Now I think there's a bit more some of the issues I had at the time can be resolved quickly.

At the moment I still don't have loads of time to work on the site (that will change after September), but I think if we can get something deployed for people to mess about with that would be a good step. The other points can follow after that.

[bguiz]

late to this 🧵 .. but I'll drop my 2c here: nextjs is likely to be quite a lot of extra overhead for a static gen site. a SSG-only tool like 11ty might be far easier to set up, and more importantly easier to self-host. (anyone tried hosting nextjs apps without vercel?).

[ninjamuffin99]

mentioned this in a PR draft yesterday, but I've begun work on a 11ty rewrite of the site. 11ty (eleventy) is a static site generator, runs pretty damn fast with buncho quality of life stuff built in (live reload), and seems (according to their development team) pretty stable / future proof.

I'm no webdev, but I found it pretty damn easy to get not just 11ty setup/configured (tbf, docpad also didn't give me tooo much fuss...)

the haxeflixel site already has a bunch of templates written in html (html.eco?) and I've found it not too hard to convert the pages and their content.

I've also gone about and implemented some tailwindcss stuff, and that also has been not too tuff.

[ninjamuffin99]

update to this

I've begun the process of porting over the site away from docpad towards 11ty Progress is currently on the dev branch, and I'm tracking progress with issue #223

At the very least... it no longer needs docpad-plugins-thumbnails! The showcase, demos, and home pages all are "ported", and thus, I was able to remove the old thumbnail generation code with a much easier solution (sharp npm package, used in eleventy-img plugin)

The ambitions for proper phase 2 is either updating or replacing bootstrap for CSS / design, but we'll get there when we get there!

[ninjamuffin99]

Allo there! PR #247 should have this issue CLOSED once it's merged, as it fully removes docpad related code relating to building / compiling the site! As mentioned in that PR there's still a tiiiny bit of work left to have it full parity with old site, todos should be in #223 and #241

I'm now poking in to inquire about the $500 (+ $250) that @gamedevsam mentioned

I'm willing to put a bounty of $500 to complete the development of the website, and an additional $250 when it's deployed and finally replaces the current docs website

If possible and not too much trouble I think it'd be nice to distribute some of this fund (via haxeflixel) towards some tech that helped along the way (via one time gh sponsors or opencollective payment)

• 11ty is the static site generator code and it has been very lovely to use, and hopefully over the next few years it can help out a lot more with site code

• Bootstrap of course is mf Bootstrap! Seems like they aren't owned by Twitter and it seems run by volunteer maintainers

• Fuse.js isn't implemented YET. But one of the next features I want to work on is a more thorough site search! And this will be the library that I think will do a good job at it

  • Site search prototype

  https://github.com/HaxeFlixel/haxeflixel.com/assets/22229331/eb49c660-c05f-4581-a840-9baab76a183d

• Liquid is the templating engine / language of choice for 11ty

• Docpad was what we used since the site was made (afaik), and I think it's worth tossing some coin that way 🙂

I'm unsure where specifically @gamedevsam would prefer to be reached for messages, but for specific amounts to be distributed and all that you can email me cameron.taylor.ninja@gmail.com or message me on discord or twitter (@ninja_muffin99) on both. However that's if this offer is all still valid!

[bguiz]

Stoked that this is on the cusp of completion! Thanks for all your work!

[gamedevsam]

I'm a man of my word, the bounty shall be honored. I will follow up up via email (PS you can scub the email from the net if you want now).

[gamedevsam]

The bounty has been paid, thank you for all your work @ninjamuffin99!

@RichardBray @Geokureli I think this issue can be closed now.