HaxeFlixel site not running locally. Should we replace docpad? #182
Comments
|
Yeah, I agree with 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. |
|
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 |
|
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) |
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. |
|
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. |
|
take your time, guys, appreciate people looking into this |
|
Going to start that soon since I can now. |
Nice, let me know how you get on 👍 |
|
@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. |
|
@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. |
|
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 |
|
@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 ;) 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! |
|
haxeflixel website we write it in haxe 🤝 |
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... |
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 |
|
Not to mention you'd just add complexity to the stack, keep things simple. |
|
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
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? |
|
Cool, we can do that. I think once Node 18 becomes LTS it shouldn't be too difficult to upgrade the dependencies. |
|
Hey all, I've started the rebuild of the HaxeFlixel site and you can see my code here @Stilic I've already added you as a collaborator. I'm also streaming my progress on YT if you're interested |
Good! |
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: 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? |
|
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 |
|
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. |
|
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. |
|
@RichardBray @gamedevsam @Stilic we have a lot of breaking changes coming in the next release and I want to update the documentation accordingly |
|
Changes to haxeflixel.com are deployed by CI on the master branch of this repo. Otherwise you could not make changes to https://haxeflixel.com/documentation/ without accidentally deploying the dev branch API docs. |
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! |
|
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 |
|
You're right, I misremembered. It installs from Haxelib. https://github.com/HaxeFlixel/setup-flixel/blob/master/src/Main.hx#L123-L128 |
|
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 DocsThis 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. DeploymentThe 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 snippetsIf 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. DisqusYou'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 postWhat 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 bitsThere 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 💪 |
|
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:
Cheers. |
|
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 |
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. |
|
@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:
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).
If you configure Next.js for static export), this will be a non-issue.
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.
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.
I recommend just recreating this in Markdown, preserve the indiegogo backers by displaying them in a bulleted list or table, ex:
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. |
|
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. |
|
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?). |
|
mentioned this in a PR draft yesterday, but I've begun work on a 11ty rewrite of the site. 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. |
|
update to this I've begun the process of porting over the site away from docpad towards 11ty At the very least... it no longer needs The ambitions for proper phase 2 is either updating or replacing bootstrap for CSS / design, but we'll get there when we get there! |
|
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
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)
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 |
|
Stoked that this is on the cusp of completion! Thanks for all your work! |
|
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). |
|
The bounty has been paid, thank you for all your work @ninjamuffin99! @RichardBray @Geokureli I think this issue can be closed now. |
|
After this donation, the balance of HaxeFlixel Patreon funds stands at $1231.61. If anyone has any suggestions on how to deploy this cash to improve the HaxeFlixel community, let me know. |
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 rundoesn't bring up the serverSo 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.
The text was updated successfully, but these errors were encountered: