Express: introduction to what is inside examples?

[alepinio]

Hi, I couldn't find any resource in expressjs.com talking about the examples in directory examples, say an introduction or a TOC.

Am I missing a related resource providing a gentler approach to what is inside directory examples? Or it's just the code?

[dougwilson]

Currently it is just code, but I agree an TOC / Markdown of what is in there would be nice. Contributions around this would be very welcome :) !

[getspooky]

It would be a good idea to add Example section to expressjs website.
I think that vuejs documentation is the best example to follow

[dougwilson]

@getspooky that is a good idea, one you should open an issue for about on the express website repo :) this issue is more about adding information about the examples to this repo.

[dougwilson]

@alepinio can you clarify if this issue you opened is regarding the express repo (where you opened this issue) or about the expressjs.com website? (i.e. the place where you would _like_ to see the listing of examples)

[dougwilson]

To me, it would make sense to keep the list as a Markdown file directly in this repository, along with the examples. Then either link from the website to that markdown file or set up some process to sync the file. That would make the act of adding, removing, and updating examples more straight forward to me, since the list of the examples would be in the same repository as the examples themselves, especially since examples are likely to change a lot more as we plan to increase the frequency of major version releases. It would also make it easy for users who want to see, for example, 4.x examples vs 5.x examples since the data is contained along in this repository with the examples, GitHub makes it simple to switch between the two by referencing by branch name or version number.

Thoughts?

[alepinio]

@alepinio can you clarify if this issue you opened is regarding the express repo (where you opened this issue) or about the expressjs.com website? (i.e. the place where you would _like_ to see the listing of examples)

Sure.

I've opened an issue here because:

1. I thought the website wasn't including an presentation/explanation of expressjs examples because of some reason, and
2. I thought there was some kind of presentation/explanation in this repo but I couldn't find it (not exactly in this case, but I usually get lost between source .mds, the wiki, GitHub pages and websites).

PS: I got to know about the existence of examples in this repo just because I was reading about Routing in the website and something was said about routing examples and..."wow, there are a lot of examples here!"

[dougwilson]

Thanks @alepinio ! So I guess I'm still not clear on one aspect of your request: is your request about adding information to this repo (where you opened the issue) or to the website (a different repo, not this one where you opened the issue)?

[alepinio]

Ahh, sorry.

I'll leave it up to you. I think that some kind of presentation/explanation, both here or in the website, would be a progress.

It would be great to have a gentle presentation/explanation to the examples in the website, but hey, that's not easy.

[rodion-arr]

@dougwilson What do you think about moving content from https://github.com/expressjs/expressjs.com/pull/1178 into this repo into separate .md file and update some existing page on site with link to this new file?

I agree that advertising these examples somehow on site will be good for people who are not exploring express source code yet and may not even know about additional examples.

At least on code-reviews for PRs changing examples folders - it will be possible to track if someone missed to update general list. Next we can think about some automation for building or just checking examples list consistency (amount of list items = amount of examples, each list item contains some description, etc)

[dougwilson]

Hi @rodion-arr yea, I think that makes the most sense in the current set up: we can land the example index as like examples/README.md in this repo, providing an index of the examples both along side the examples and to folks who directly explore this repo.

But then we should still land something on the expressjs.com website around the examples. In PR https://github.com/expressjs/expressjs.com/pull/1135 I created a generalized method to automate pulling in Markdown from this repo and making a copy on the website without needing to maintain it twice but giving it better visibility. I will get that PR landed so you can use it -- it was waiting for comments but none came so I guess it's good to go.

It would mean your expressjs.com changes would still be creating a new Examples page, but then adding <!-- SRC: https://raw.githubusercontent.com/expressjs/express/master/examples/README.md --> to the page and running a script to pull down the contents onto that page. We plan to turn that into a GH action at some point, but it's at least some method to keep it from needing to keep two copies by hand -- similar to how we are doing all the middlewars docs in http://expressjs.com/en/resources/middleware.html

[Abdurahmanm2020]

Here is a web that helps you on things. NPM

[crandmck]

@alepinio This is a great suggestion, thanks for it!

I've long (too long, sorry :-( ) wanted to do something along these lines, per https://github.com/expressjs/expressjs.com/issues/463, and if you want an issue in the website repo, feel free to use that one. Also, I don't know if my notes at https://github.com/expressjs/expressjs.com/wiki/Example-notes would be of any help. .... It may be outdated at this point, I don't know.

I've been a bit out of the loop for a few months, but I plan to get back into the project; LMK if I can help with this.

[dougwilson]

haha, I forgot all about that open issue @crandmck ! Now that we will have this README.md file in the examples directory, we can always continue to iterate on it, like expanding the descriptions on the page, or even adding individual README.md files to each example directory--whatever makes sense.

Ultimately having them appear on the website I think is the ultimate goal of course, as that will be the most discoverable location.