Add blog
crandmck opened this issue · comments
In the TC meeting, @UlisesGascon suggested that we add a blog section to the website for security notices and other timely information, and I wanted to record this idea before it slipped away. I think there's a lot of value in this kind of information, which is somewhat outside the normal scope of documentation, and eventually we could get guest submissions from the community on all kinds of topics of general interest to Express devs.
Jekyll was originally a blog, so it's got lots of features for blogging.
What type of features? I assume you just mean that blog posts would be committed by your team (or others w. your permission) as files added the blog folder. Like by developers who know how to do such things.
Meaning, you don't expect an markdown editor w. the ability to create new posts within the site itself, and authentication, etc, where hitting "submit" creates a new post.
Adding a editor and blog post capabilities is possible for me to do, but if authentication does not already exist, then anyone could post.
If I understand I assume you don't want that. So we'd just need to add a blog link to the nav and then serve any posts from the blog folder, which Jekyll does very easily.
I can handle this if you confirm this will work.
@chrisdel101 Thanks for offering... And yes, by "features" I was just referring to basic Jekyll blog features, i.e. as explained in https://jekyllrb.com/docs/posts/. As you say, the idea is that new blog posts would be written/published using the current GitHub/PR flow as for the rest of the docs.
IMO, the minimal work to add a blog would be:
- Add a new layout template in
_layoutsfor blog posts. Nothing fancy, but will be a bit different from a regular page in the site. Should still display the site menu, presumably. - Add a blog index that displays links to all the files in
_postsalong with publication date, authors, and a short excerpt for each. Perhaps highlighting the most recent post ... - Add a menu item that links to the above; Either a new top-level item to the right of "Resources" or an item in the "Resources" menu. Exact UX is TBD based on input from TC, et al.
I might be missing some other steps, but that's the general idea. Until we have some "real" blog posts, just start with a "Welcome to the Express blog" placeholder post that explains HOW to write a post and submit a PR to publish it.
Once this framework is in place, I hope folks in the TC and others will start writing posts with real content.
Okay, will look into this.
So I have created the ability to add posts and display them. I've add two dummy posts to test and taken a screen shot. These won't be commited with the feature.
I've also shown what will happen when there are no posts, as I guess there will not be right after this change is made. If you were to run this now, you would see the second one.
The task now is to decide how we want them laid out, I mean on the index page above. We can have them in one long list like they are now, or group by months, or by quarter, or by topics. Any input on that?
We can also add tags to each post if you want to track them this way.
I think the layout of the posts themselves can be dictated by the authors? Since they'll be writing them in HTML or MD.
I will also add the rest of the stuff you asked for in next commit: publication date, authors, and a short excerpt for each. Can also highlighting the most recent post.
Oh, and I guess will fill in the currenrtly empty space with an explanation of how to write a post, as you suggest above too
This is great @chrisdel101 ... Thanks for taking this on!
The task now is to decide how we want them laid out, I mean on the index page above.
I think initially, just a reverse chronological list, i.e. with the most-recent post first, followed by the one before that, and so on... That should be fine until we have more than a handful of posts, at which point we can discuss dividing them by month, quarter, or whatever, depending on how often we have posts. We just don't know yet, since we haven't had a blog before!
Each post in this list should include title, publication date, author(s), and excerpt (maybe, see below).
I think the layout of the posts themselves can be dictated by the authors? Since they'll be writing them in HTML or MD.
Yes, but it might be nice to display a list of posts/links in the left gutter (otherwise empty), without all the extra stuff (author, date, etc) to provide a kind of navigation among the blog post.. This is similar to how the API reference works. If we do this, then the blog "home page" could always show the complete most-recent post, and the links in the left gutter would link to older ones.
Alternatively, the "home page" would show the list of all the posts with short excerpts, and perhaps the most-recent one would have a longer excerpt. I think the first way is more common, but I'm open to either approach.
Otherwise, having the blog post layout the same as the current page layout seems fine to me. We do need to think about how the authors and date will be displayed... As sub-headings below the title, presumably. Otherwise, at your discretion.
Re: tags, I think that's a great idea that would be helpful in the long run, but I think we can live without it for the initial incarnation. It won't even be relevant until we have a number of posts, and as previously noted, this is so new it's hard to know if/when we'll have many...
Just wanted to give an update on this and make sure things are going in the right direction. I looked at some other blog designs; didn't want to get too fancy + almost did.
On the /posts page each post gets it's own box in order by date. The first gets a blurb excerpt. The biggest issue here might be that there is a photo on each post. Either the author would need to point to that with their post, or attach it with their file. Or we could randomly assign it...or I could get rid of it.
The gutter menu shows the tags. When clicked all the posts with that tag are shown. We could always hide this if there aren't a minimum of say five tags? If there's something better to put here that's an option too.
If this looks good, I'll keep tidying it up.
This looks good as far as I can tell, but it's a bit hard just from the above...
If you could open a PR, now that we have deploy previews (thanks @jonchurch), we could see how it looks in action. Then I might be able to give more specific/useful feedback.
makes sense. i’ll get something presentable ready before asking feedback further. making a PR like you said sounds good.
i’m having some trouble with the navbar. it seems weirdly put together. it’s breaking with the addition of an extra item in there. once, and if, i sort that out i’ll put this through for you to look at.
Hey @UlisesGascon. Do you mind if I create my blog post pull request once the blog’s structure is officially merged? It’ll make it easier for me to format it. 😊
Hey @UlisesGascon. Do you mind if I create my blog post pull request once the blog’s structure is officially merged? It’ll make it easier for me to format it. 😊
Yeah! no problem :)