Instance specific customization

[kdp-cloud]

• Introduced new config variables for other instances of FAIRDOM-SEEK, with defaults

seek_instance:
  name: "FAIRDOM-SEEK"
  url: "https://fairdomhub.org"

• Added a new layout for customizing the page's title with the instance name
• Replaced 'FAIRDOM-SEEK' with the instance's name where (I think) it makes sense
• Idem for 'https://fairdomhub.org', which is replaced with the instance's url
• Added an extra section on the home page describing the instance itself. This is only rendered if the instance name is different from 'FAIRDOM-SEEK'
  
  
• Closes Use more config variables for FAIRDOM SEEK mentions #20

[PhilReedData]

Thanks Kevin, I'll check this carefully in the next few days.

[kdp-cloud]

Thanks @PhilReedData! I just want to add here that I like other instances can easily personalize their docs but this will make it more complicated for contributors, as they now have to think about "Do I mean the FAIRDOM-SEEK software, or do I mean the instance's name". I feel that if we go down that route, we should carefully document this.

Also for the page title, I needed to add some javascript that changes the title client-side, which is definitely not my preferred way of doing things. But as far as I know, you can't make variables in front matter dynamic and this is the only solution I could come up with. If you know of a better one, do let me know because I'm not much of a Jekyll expert.

[PhilReedData]

Good point, yes we need to be careful here and document it, and keep things as simple as we can.

Did you see Stuart's comment in the issue, that sometimes it will be appropriate to say 'FAIRDOM-SEEK' rather than the name of the instance, for example when talking about the overall platform.

I've put aside time on Tuesday morning next week to dive into this.

[kdp-cloud]

Sorry to come back on this but I'm actually really not happy with the JS I added in the layout because we will run into SEO issues since the HTML still says 'FAIRDOM-SEEK' in the title. Could we, instead, just not put 'FAIRDOM-SEEK' in the title? Or just mention it in the title where it makes sense?

[PhilReedData]

This is very good. I've left a few questions.

I'm still not sure about the instance-specific layout, what pages this is required for; this should be explained in the web contribution page /tech/contributing-to-pages.

[PhilReedData]

Good spot with removing the legacy SEEK application folders in .gitignore.

[PhilReedData]

Would this URL ever change? The text before the link says FAIRDOMHub, so surely the link should always go to FAIRDOMHub API?

[PhilReedData]

This time, you've put the variable in the instance name too. So perhaps line 18 should have the instance name variable as well?

[PhilReedData]

In this case, would the example work in every SEEK instance? If they were not upgraded to the relevant version to support wild card search queries, the example would fail. Might be better to leave with the tested default for everyone here. What do you think, @stuzart?

[kdp-cloud]

This was done by mistake. I'll revert it.

[PhilReedData]

Sorry to come back on this but I'm actually really not happy with the JS I added in the layout because we will run into SEO issues since the HTML still says 'FAIRDOM-SEEK' in the title. Could we, instead, just not put 'FAIRDOM-SEEK' in the title? Or just mention it in the title where it makes sense?

I would like to check with @bedroesb about this, please. Bert, may I ask, what is the reason for having the site title with every page title? I thought it was good for SEO.

[PhilReedData]

I also liked the additional content to show up on instance-specific sites only, to explain what FAIRDOM-SEEK is and link to the parent documentation. I will consider this when Stuart, Munazah and I review the homepage/get-seek pages in my PR tomorrow.

[bedroesb]

@PhilReedData In the HTML, Head, this is already added to the title automatically based on the site.title variable in the config. The code:

{% if page.title %}{% if subtitle %}{{subtitle}}: {% endif %}{{ page.title }} | {{ site.title }}{%- else %}{{ site.title }}{% endif %}

This is indeed good SEO and I would not change this.

@kdp-cloud there might have been a misunderstanding. I would not touch the title attribute in the config of the deployment and replace it with the SEEK variables. I would rather reuse the title variable.

[bedroesb]

So in short: I would take out the mention of FAIRDOM SEEK in the H1 titles, so the ones from the page metadata:

---
title: FAIRDOM SEEK
---

And reuse the website level variable title. were possible, which propably contains the word documentation. And the Seek variable for the scenarios where you use the instance name without the "documentation" word.

I also would not use custom layouts accept when really needed.

[bedroesb]

So not using a custom layout, but taking out the mention of FAIRDOM SEEK here, since the site.title is adding FAIRDOM SEEK Documentation in from of the page title anyway for SEO.

SOrry if this was all clear already!

[PhilReedData]

There are many places (in both user guide and technical references) where the page title includes a 'duplicate' mention of FAIRDOM-SEEK. I haven't changed any of these (other than update from SEEK to FAIRDOM-SEEK where necessary) but yes, they are no longer as useful as they were before we moved to ETT.

Technical References: Some are still useful written out in full, like

• Installing FAIRDOM-SEEK and
• Contributing to FAIRDOM-SEEK which I think should stay (at least the contribution one) or change it to 'Contributing to the code'.
• Similar for Administration, Backing up, other Installing pages. Could change to things like 'Administration of the software' but I would prefer to see the name of the software here.

User Guide: These could be shortened?

• Using FAIRDOM-SEEK with openBIS would become 'Integrations using openBIS', do you think? (The parent menu folder says 'Integrations'.)
• Registering in FAIRDOM-SEEK becomes 'Registering'.
• Logging into FAIRDOM-SEEK via LS Login becomes 'Logging in via LS Login'.
• Using Copasi in FAIRDOM-SEEK becomes 'Integrations using Copasi'.

[PhilReedData]

Suggested change

	url: "https://fairdomhub.org"
	instance_url: "https://fairdomhub.org"

From Bert's suggestions, we would modify _config.yml to have:

title: "FAIRDOM-SEEK"
instance_url: "https://fairdomhub.org"

And the word " Documentation" would be added in the code where required.

[bedroesb]

or having them both:

title: "FAIRDOM-SEEK Documentation"
seek_instance:
  name: "FAIRDOM-SEEK"
  url: "https://fairdomhub.org"

this way title is still used for SEO, and FAIRDOM-SEEK can be used inside the content of the website