XSpec website

[cirulls]

It would be nice to have an official XSpec website - every time I google xspec I end up with some NASA module or cryptocurrency! I was thinking of implementing a basic website via GitHub pages as it allows to host a static website directly from GitHub repositories. AFAIK, there are two ways of hosting a website via GitHub Pages:

1. Creating a brand new repository inside the XSpec organisation and call it xspec.github.io.
2. Creating a folder docs at the root of the existing xspec repository.

I think the first option could be useful if we want a generic website, for example just few static pages to promote XSpec. The second option could be useful if we want to include and maybe automatically generate official documentation for XSpec and bundled it with the xspec repository.

If you have a preference or ideas I would be very interested to hear them! Also, if anyone is willing to writing pages for the website or has some design skills, it would be very useful too.

@cmarchand: I remember you bought the domain xspec.io. Do you think we can use this domain name for the official XSpec website?

[cmarchand]

@cirulls : yes, I've bought xspec.io for this, and I'll be happy to give this to XSpec community. Actually, I own this domain until 2020/01/01, but I can renew it for 5 more years. Or 3, it depends on the amount... It'll cost you one or two beers at XMLPrague 2020 !

[cirulls]

@cmarchand: thanks, that's really useful, I'll pay back in beer 🍺🍺🍺 I may contact you privately for the domain name, I remember you gave me some credentials in the past, but I'll double check first.

[AirQuick]

The 1st option is only one per organization and in a dedicated repository, and the 2nd option is per repository? The 1st one sounds better then, because the site would need to cover all the organization repositories and the 2nd option would be difficult to relax access control. Just my quick thought.

[cirulls]

Yes, option 1 is a dedicated repository and can include everything related to XSpec while option 2 is tied to the specific repository where the docs directory lives.

I'll favour option 1 as it is more flexible and we have all our documentation in the wiki at the moment. In case we want to autogenerate documentation in the future we may want to revisit the docs directory option.

[rolfkleef]

You could actually mix the two: if you publish xspec.github.io under the xspec.io domain, and then publish the docs directory of the xspec repository, it will be available as xspec.io/xspec. With a bit of planning and tweaking templates it can look like an integrated site with a general overview and a dedicated "reference section".

[cirulls]

Thanks for the tip @rolfkleef, I didn't know it was possible to mix the two options. I'll have a look when I start tackling this issue (any help is welcome!)

[cmarchand]

@cirulls : at this time, I do not own xspec.io anymore. I'm gonna try to re-buy it.

[cirulls]

@cmarchand: thanks for flagging this, keep me posted when you manage to re-register the domain. Thanks!

[cmarchand]

Done. I'm able change DNS when you want.

[AirQuick]

Also it would be nice if we had a handy org-wide facility to publish casual messages.
https://github.com/semantic-release/twitter-together looked nice. I created a twitter account for experimenting it. Very soon after creating the account, it got locked. I just gave up.

[cirulls]

Would it be something like a blog area to announce new releases? Or just a twitter feed showing messages?

I'm planning to focus on a website for XSpec in the next weeks, I can't promise when it's going to be ready but I'll start putting something together.

[AirQuick]

More like a blog area. But a blog would be too heavy and not so viral. That's why I thought a shared moderated Twitter account like https://github.com/semantic-release/twitter-together might be nice. It utilizes https://github.com/marketplace/actions/twitter-together.

[cirulls]

Ok, I'll add it to the requirements. I'm planning to use a static website generator like Hugo in conjunction with GitHub Pages so a blog area could also be as lightweight as editing a text file. It would be nice to have a dedicated Twitter account to post to, it could help spread news like new releases and functionalities. Once I have something working I'll share it here.

[cirulls]

I set up an initial draft of the website at https://xspec.github.io

The website is set up using GitHub Pages and Hugo, I mainly followed these instructions to generate the website. The HTML/CSS generated by Hugo is in https://github.com/xspec/xspec.github.io. In the next days I will also commit the Hugo configuration that generates the HTML/CSS (I first need to work out where to put it in the repo).

Few notes on this initial setup:

• Design: I used the Hugo theme hyde-hyde as I found it simple and clean. However, it is possible to install and try out other themes.
• Blog: There is a blog section with a blog post just to give an idea. Creating new blog posts is as simple as adding a new Markdown file to a given directory. This should give us a lightweight blog area where to post announcements, messages, etc.
• Twitter: There are social icons linking to GitHub (the main xspec repo) and StackOverflow (questions with hashtag xspec). There is also an icon for Twitter although I don't think we have a Twitter account for XSpec yet. I'm not sure if it is possible to add any dynamic content in Hugo in order to generate a twitter feed but I can investigate this further.
• Content: Regarding the content I mainly copy-pasted some text from the wiki in order to create menus and pages. I think it would be good to mention other tools in the XSpec ecosystem (maven plugin, oXygen plugin, etc.). Feel free to share ideas on which additional content should be added.
• Deployment: My plan is to update the content of the website via our usual pull request mechanisms. As soon as a pull request in repo xspec.github.io is merged into master, a deployment script generates the static pages and updates the website. I'm thinking of using this procedure.
• Custom Domain: @cmarchand registered xspec.io and it would be nice to set up the custom domain so that we can have the XSpec website at https:///xspec.io

Feedback and ideas are welcome!

[AirQuick]

I like the neat design. And your plan to update via pull requests sounds good. Thanks for the step forward.

[rolfkleef]

I've created a pull request for a Github Action that can generate the site from a separate branch (I've picked cms but it any name will do). The issue with organisation repositories and Github pages is that you can only publish from the master branch (for others you can choose to use a gh-pages branch or the /docs folder, but not here).

So with your Hugo sources on branch cms, pull requests accepted into that branch will update the site.

[cirulls]

Thanks @rolfkleef, that's great! I'll have a look at the PR and let you know in 1-2 days.

[rolfkleef]

Thanks for merging @cirulls! I was able to checkout and run your sources as hugo branch locally. Perhaps good to take further issues to the new repository and close this one?

I can help migrate the wiki here to the new repository, if that suits @AirQuick as well?

[AirQuick]

Thanks @rolfkleef and @cirulls
Some wiki pages are linked directly from other sites. It would be helpful if we could lead visitors of each page to its corresponding new page after migration.

[cirulls]

@rolfkleef: Thanks for testing, good that it works at your end too. Yes, I think we can close this issue (as far the website work is concerned) and move further work on the website on the repo xspec.github.io. Feel free to open issues and PR there.

Regarding the wiki pages, my original idea was to keep the XSpec wiki where it is (https://github.com/xspec/xspec/wiki) and provides links from the website to the wiki. But I am open to discussion. Where do you think the documentation should live?

[AirQuick]

Wiki is easy to edit but collaborating on it is not very easy. Migrating to website would solve it probably?

[AirQuick]

Ah, but the current website lacks search. That would be critical for documentation purposes.

[cirulls]

It is possible to integrate search with a hugo website: https://gohugo.io/tools/search/

If this is a requirement for migrating the documentation to the website and allowing better collaboration, I can invest some time into implementing the search functionality on the website.

[AirQuick]

It would be appreciated if you could integrate some search functionality. Whether we migrate Wiki or not, searchability will be welcomed by everybody.
Any recommendation, @rolfkleef ?

[cirulls]

Sounds good, I'll try to implement a search functionality for the website. Feel free to post any other requirements. I'll probably migrate them as issues in the xspec.github.io repo over the weekend so that we can close this issue here.

[rolfkleef]

Hi @cirulls @AirQuick - my time/availability is a bit scattered, but I've taken the liberty now to add a couple of issues to the new repo based on comments in this thread. Great to see so much happening for xspec itself, I hope to contribute a bit more to the website in the coming months!

[cirulls]

@rolfkleef: thanks for raising the issues, I plan to work on the search functionality in July, I'll ping you when I have something working.

I'm closing this issue since the website is up and running and follow-up tasks have now been created in the xspec.github.io repository.