Consider generating GitHub Pages to show what data is available in this repo

[ronaldtse]

[ronaldtse]

@andrew2net : @CAMOBAP can help apply this workflow to all relaton-data-* repositories.

[andrew2net]

@ronaldtse the most work here is to create indexes in all relaton-data-* repositories. Not every repository has an index yet. And I started thinking about relaton-index gem. The reasons are:

• The existing indexes have different structures. I think we should unificate them.
• Some parts of code repeated in index generators.

The index gem should:

• register fields for indexing
• read existed index file or create a new emplty index if file odesn't exist
• add element to index
• search element in index
• save index to file

As we have a same formated index in every relato-data-* repository, we can easely generate index pages using same Jekyll template.
Any thoughts?

[ronaldtse]

@andrew2net I agree that the very first thing is to have the same index structures across all Relaton repositories.

An index is really a subset of the Relaton XML/YAML information of a Relaton collection, in a form that can be easily accessed and searched.

Remember that the Metanorma site generate command creates the mini site based on RXL (Relaton XML) information? This is exactly like the purpose of the Relaton index site -- look at standards.calconnect.org.

We should extract that code and consolidate such code into relaton-index.

[andrew2net]

@ronaldtse the GH pages don't allow Jekyll to run any code except Jekyll's core functionality (for security reasons). So we just can put index.yaml into Jekyll's _data folder and use fields from the index file in a template to generate an HTML index page. It seems Jekyll has pagination in its core functionality, but searching through all pages isn't available in the core functionality.

[ronaldtse]

@andrew2net that's not entirely correct. GitHub Actions can run Jekyll in full, and all you need is to run the https://github.com/actions/deploy-pages actions to upload a ZIP file with index.html.

[ronaldtse]

Have a look at https://github.com/actions-mn/build-and-publish/blob/main/action.yml

[andrew2net]

@ronaldtse I apologize for the incorrect statement. I have tried to create a custom plugin to generate an index.html directly from documents in the data folder, but I was unable to make it work. It highly likely happened because I used a github-pages plugin instead of jekyll gem. It said the plugin doesn't allow any plugins except the list.
If we can create a custom plugin and run it with GHA then we don't need to have index.yaml to create index.html. We have documents in the data folder. Every document has an ID and title. So the custom plugin can just read each document and generate the index.html. I'm sure this approach is better than using the index.yaml for the following reasons:

• I think it's not a good idea to put titles into index.yaml. We don't need titles for searching but the size of the index.yaml file will be increased significantly.
• We can create index pages right now. We don't need to create the relaton-index first.

[ronaldtse]

@andrew2net there's no need to apologize... yes I think that is what happened.

If we can create a custom plugin and run it with GHA then we don't need to have index.yaml to create index.html. We have documents in the data folder.

If we do not want to run a Jekyll site in full, we can actually just generate a new *.adoc file per bibliographic object (generated through YAML) in addition to having the YAML in _data/. We can also publish the index.yaml directly because ultimately we need a machine-readable form.

UPDATE: I just noticed that https://pages.github.com/versions/ does not have jekyll-asciidoc. Maybe this will help? https://stackoverflow.com/questions/53215356/jekyll-how-to-use-custom-plugins-with-github-pages

For index.yaml, we will need to provide "identifiable elements" to allow location of a desired resource.

For example, elements like

• identifier
• edition / edition year

are used to locate a resource.

[andrew2net]

We can also publish the index.yaml directly because ultimately we need a machine-readable form.

@ronaldtse do we need pages for users or machine-readable? I supposed we need list of references for users. The indexes are machine readable itself.
In case we need reference lists for users, I think it would be better to generate JSON file with references and titles and implements Javascript powered page with pagination and search. Do you agree?

[ronaldtse]

@ronaldtse do we need pages for users or machine-readable? I supposed we need list of references for users. The indexes are machine readable itself. In case we need reference lists for users, I think it would be better to generate JSON file with references and titles and implements Javascript powered page with pagination and search. Do you agree?

For both.

Agree to use JS powered pages for pagination, but we also want static pages to allow Google to index.

[andrew2net]

@ronaldtse check please https://relaton.github.io/relaton-data-oasis/
If it's ok then I suggest to make a GH action repo relation-index-page and use the action in all relaton-data-* repos.

[ronaldtse]

@andrew2net thank you for this!

Can we make the page more compact (less spacing) and provide the full doc id for citing, i.e. "Use DocID OASIS genericode-v1.0 to refer to this item"?