hilverd / glossary-page-template Goto Github PK

View Code? Open in Web Editor NEW

97.0 4.0 3.0 2.38 MB

A single HTML page with a built-in editor for creating a glossary that can be hosted anywhere.

Home Page: https://glossary.page/template

License: MIT License

HTML 4.17% JavaScript 0.23% Elm 90.34% CSS 2.52% Shell 0.57% TypeScript 2.17%

glossary

glossary-page-template's Introduction

Glossary Page Template

This project makes it easy to create a glossary as a single HTML page that can be hosted anywhere.

Features

Includes integrated (single-user) editor UI that saves changes back to the HTML file — requires Node.js.
Represents a glossary as a standard dl element for accessibility and portability.
Supports different screen sizes using responsive design and includes dark mode support.
Write in a Markdown-based syntax.
Supports math typesetting using KaTeX.

Getting Started

Download glossary.html from the latest release and open it in a browser.

Static assets

The HTML file points to glstatic.net for static assets hosted using Cloudflare:

https://glstatic.net/glossary-page-template@4/glossary.min.js
https://glstatic.net/glossary-page-template@4/glossary.min.css

The above assets are cached for 24 hours and get updated with any releases with a major version number of 4. Alternatively you can change the URL to point to e.g. @4.1 which gets all patch releases with version numbers of the form 4.1.x. You can also use a specific version such as 4.1.2 — these are cached forever.

Security considerations

The approach above is the easiest one, but the safest option would be to either host the static assets yourself and/or use Subresource Integrity (SRI) by specifying hashes for the static assets.

To host the static assets yourself, you can get them from the .tar.gz package in a release, which also contains a glossary template file that uses them.

To use SRI, change the two lines at the end of the <head> element so they

point to a specific version of the JS and CSS files,
have a crossorigin attribute, and
have an integrity="hash-here" attribute.

You can get the hash-here values from the release notes.

Known Limitations

The integrated editor UI is meant to be run and used by a single local user only. It is not designed to be exposed to untrusted users.
In its current state this project is not very suitable for glossaries of more than (say) 500 items. At the moment everything is stored in a single HTML file, and the DOM size and browser memory usage grows as the number of items does. (I'm planning to address this.)

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

This project is mainly written in Elm and relies on elm-markdown for parsing and rendering Markdown. The UI is based on components from Tailwind UI. Most icons are from either Heroicons or Lucide.

Thanks to everyone who contributed suggestions for improvements.

glossary-page-template's People

Contributors

Stargazers

Watchers

Forkers

acumenix esyjournal rolandshield

glossary-page-template's Issues

Numbers, their positions and "hide order"

Hi,

Great project, really easy to use, thank you so much for creating it. Just a couple of things...

My glossary items include numbers (i.e. 3040) - is there a way to make them appear at the top of the glossary? Currently they appear at the bottom.

Also, if my numbers have a letter in (654n for example), they get sorted with the "n's". is there a way to stop that and force them to still be a number?

Finally, is there a way I can hide the "order items" stuff at the top? Something like the way you can hide "Export" etc. would be great.

Thanks.

Need help to edit the html file

This is really an elegant solution to make a glossary page. I see a lot of potential here. After downloading the file and installing node.js on my Windows 10 machine. I couldn't wait to fire up the following command on my cygwin terminal. Here is the command:

$ sed -n '/START OF editor.js$/,$p' glossary.html | FILE=glossary.html node
Server started at http://localhost:3003

Then I open the browser:
http://localhost:3003/glossary.html

I can't find anywhere I can edit/add/delete the glossary terms.

Can someone shed some light here, please? I know the author recommends MacOS or Linux, which I do not have access to. Instead, I hope I can edit it on Windows and then deploy it to our hosting service.

On the other hand, can someone show how I may hide the 'EXPORT' option which shows in the top right corner?

Thanks.

Jeff Jiang

Main home page is broken/404

Cool project!

Just wanted to point out that the main URL (https://glossary.page/) doesn't redirect to anything and seems to throw an error in the browser. Maybe it should direct to the /template page?

Need multiple language support

Hello. First of all, it's a great system. Mainly the UI part. I would like to thank everyone who contributed.

The system currently supports one language. All static words are in English. Can you add multiple language support to the system? There is no language option in the menu. It is enough to have a json file for each language inside the code (for example, en.json). I can rename the json file before building and rebuild that way. I want to use it as a dictionary. I want all the content of the site to be in the same language. I tried changing the static words from within the code. But this is very difficult. I think it would be great if you could add multiple language support to the system.

P.S Sorry for my English

Concurrent multiple edits results in loss of data

Hi,

I see that two different browser sessions editing the glossary at the same time results in loss of data (the last save is what is stored in disk and other changes are ignored).

I plan to solve this by doing a GET request to fetch the latest data before sending the PATCH request. While this still doesn't give a 100% safety against many concurrent users, might work for most of the users. Let me know if that approach works well or is there a better way to do this.

Uncaught TypeError: Cannot read properties of undefined (reading 'childNodes')

It keeps throwing this error as I try to add an item. Sometimes I cannot even Save the item, it just gets stuck there until I terminate the server.

Thanks for making this tool, I plan on using this as my Vocabulary Journal. Cheers : )

Would it be possible to get the ability to add links?

Hi I love this template and I want to write a url-rich documentation, but I found it wouldn't work if I put something in like <a href="https://www.w3schools.com">Visit W3Schools</a> , would you consider add that kind of functionality? Thank you, it is a simple and elegant project

Would it be possible to get the ability to add images?

It seems like the javascript is deleting my img tags. They don't even show up in the DOM.

Feature or Option to Display One Definition at a Time

Remarkable template Hilverd! We are currently exploring ways to rebuild our Mathematics Glossary on the Alberta Education's LearnAlberta.ca. Each term definition could have a number of media types, like images, video and HTML5 interactive pieces displayed in the definition display frame. If we incorporated a version of your template it would need to load just the selected definition into the frame where you currently show all the definition cards. I would love to hear your thoughts? Here is a bit of a mockup. Thanks so much!

adding tags to definition and filtering by tags

Great project! I was thinking about the possibility to add tags to definitions and then filtering by selected tags. The tags would be like categories and would provide ways to separate contexts. Looking forward to hear your thoughts on that