Current Express.js Website

[blakeembrey]

This was brought up during this weeks weekly discussion, but contributing to the current Express.js website is difficult. Some reasons around that difficulty is because the Markdown is not actually pure Markdown and the build toolchain is hard to use.

I'd like to take some time to open a PR that'll refactor the website into a Markdown only workflow with a JavaScript-based build step. This would fix previewing contributions inside of GitHub, and all Windows users to contribute easier.

Any objections, or concerns, I should be aware of?

[mikeal]

You're welcome to steal any code you want from the Node.js website :) https://github.com/nodejs/nodejs.org

[blakeembrey]

Interesting, thanks for the link. That's actually the exact same process I was going to put in place - I've been doing the same for a couple of other sites for the last couple of years.

[crandmck]

Sorry I didn't see this issue sooner... I haven't been watching this repo (am now).

@blakeembrey Could you please open a parallel issue in https://github.com/strongloop/expressjs.com since that's where most of the work will actually occur? That would help to ensure that anyone else not watching here can be involved in the discussion.

I'm totally for making the site easier to contribute to, but I just want to understand the perceived difficulty. The "build" (to run the site locally) consists of a single command jekyll s once you've installed Jekyll. Wouldn't adding a JS build step add to the complexity?

I understand that running Jekyll on Windows is problematic, and I can see how that would be a problem. http://jekyllrb.com/docs/windows/ does have some tips, so perhaps it's less of an issue that it has been previously. I don't use Win atm, so I'm not in a position to say.

I can see that not using pure md could be an issue, because it breaks the preview in GitHub. Jekyll uses Kramdown we also do some custom styling. There is also some stuff we changed for translation (e.g. code blocks), which we could revert if they are a problem. If there's a way to improve on that using a JS build step, then that would be great. I have to admit I don't really understand how that would work.

Again, I'm definitely in favor of making the site easier for people to contribute to, but this is the first time I've heard any complaint about it. I thought we were getting quite a few contributions (a handful a week from the general community), but perhaps we could get a lot more..?

I think having some more specific discussion in the repo would make sense.

[blakeembrey]

No. Assuming you have node installed (which, you probably do, contributing to Express.js docs), it'd just be node build.js. The linked node.js docs are a good example of what the build would actually look like. I'm all for building an example PR with instructions for you, if you can see if it's suitable. Admittedly, I've only looked at https://github.com/expressjs/express-api-docs - should I be contributing to the repo you linked to instead?

[crandmck]

Well, https://github.com/strongloop/expressjs.com is where http://expressjs.com comes from currently and where all the doc effort has occurred previously. When I finish the work we discussed in the meeting today, the API docs will come from https://github.com/expressjs/express-api-docs (and be published to http://expressjs.info).

I think it would make sense to wait until I finish that work before starting your PR, but if you really want to do it now, go for it. Just be aware that some stuff will change...

[blakeembrey]

I'll wait, just wanted to check 😄 Just ping me (or I'll see the PR) when that's done, and I can go over it with the changes for you to review. The full breadth is a bit bigger than what I was originally looking at, but still shouldn't take long to update.

[crandmck]

OK, thanks. I will keep you posted. I will try to complete it this week, but things are kind of crazy on other fronts at work.. so I can't promise... but I will try.

[crandmck]

Just an update for anyone following this. Current status is that (per last week's TC meeting) the website repo and domain name are going to be transferred to the foundation. Once that occurs, we can re-assess what we need to do.

Hopefully, the transfer will happen soon-ish. Until then, it doesn't make much sense to put effort into https://github.com/expressjs/express-api-docs or other repos.... So until then, this issue and related work is just "on hold".

[crandmck]

I'm going to close this since the doc repo is now in this org. @blakeembrey if you'd still like to pursue this, please open an issue in https://github.com/expressjs/expressjs.com and we'll take the discussion there.

BTW, the item

... the Markdown is not actually pure Markdown

Is being addressed in expressjs/expressjs.com#597 which also includes changes to bring the build toolchain in line with standard Jekyll procedures.