4 ms·

Show HN: Glossary page template with a built-in editor

52 points by hilverd 4y ago

This started out as a static HTML file, being used by some developers at my current employer to document "domain terminology" relevant to products we're building. Soon it became too much work to update the items in the HTML manually, so I added a JavaScript-based editor. It relies on a tiny Node.js server to write changes back to the HTML file. Not as user-friendly as a "normal" web-based application, but it does mean we can keep the HTML file under version control and follow our normal development process for making/tracking changes.

ivansavz 4y ago
So what is the deploy path here? Am-I supposed to save the html to a given dir, then run the server in the same dir? https://github.com/hilverd/glossary-page-template/blob/main/examples/open-glossary-of-edge-computing.html#L2010-L2111 https://github.com/hilverd/glossary-page-template/blob/main/...
- michaelsmanley 4y ago
  If you just open the file in a browser, it provides deployment instructions. I thought it might work like Tiddlywiki, so I tried that first. Not a bad little hack. Every time I start work in a different business, I start a glossary. I have considered a specialized web application for that purpose, but always end up just creating a Google Doc or a wiki page, depending on what the company uses.
  - hilverd 4y ago
    Yes -- you beat me to it :-). The built-in server is meant to be run only locally/offline (typically by a developer), just for making changes to a glossary. If you download and open the template (not one of the "full" examples) in a browser, then it tells you how: sed -n '/START OF editor.js$/,$p' glossary.html | FILE=glossary.html node Then you would host glossary.html (and maybe the CSS and JS if you don't want to point to the CDN) wherever you want, as it's just a static web page. I will make this clearer in the documentation -- thanks!
oefrha 4y ago
Maybe render the Jargon File in this format? Although it might be too large for a single page. http://www.catb.org/jargon/html/ http://www.catb.org/jargon/html/
- hilverd 4y ago
  Thanks, I had been looking for existing glossaries with permissive licenses to use as examples, and this one wasn't on my list yet. It does look way larger than any of the other examples. But it would be interesting to explore what sort of changes would be required to the template to keep it usable in practice.
  - tutuca 4y ago
    The jargon file is trully an amazing relic. I love to get back to it from time to time. Your tools looks like an amazing overvamp for it! Great work!
1023bytes 4y ago
It might be possible to do this without the Node.js server by using the File System Access API https://web.dev/file-system-access/ https://web.dev/file-system-access/
- hilverd 4y ago
  Interesting, I hadn't considered that -- thanks. I was just having a look and it seems that right now, only Chrome and Edge (and Brave?) support that API. I'll keep an eye on it, because it doesn't seem like a viable option yet until Safari and Firefox also do.
  - 1023bytes 4y ago
    It's possible to do this in Safari and Firefox as well, it's just that the experience isn't as seamless - instead of writing to the existing file a new copy will be downloaded. You can see this in the demo here: https://googlechromelabs.github.io/text-editor/ https://googlechromelabs.github.io/text-editor/
unraveller 4y ago
A similar project is imml, meant for textful landing pages, you can version the underlying imml file or the output html. https://leoncvlt.github.io/imml/ https://leoncvlt.github.io/imml/

52 points by hilverd 4y ago

ivansavz 4y ago

So what is the deploy path here? Am-I supposed to save the html to a given dir, then run the server in the same dir? https://github.com/hilverd/glossary-page-template/blob/main/examples/open-glossary-of-edge-computing.html#L2010-L2111 https://github.com/hilverd/glossary-page-template/blob/main/...

michaelsmanley 4y ago
If you just open the file in a browser, it provides deployment instructions. I thought it might work like Tiddlywiki, so I tried that first. Not a bad little hack. Every time I start work in a different business, I start a glossary. I have considered a specialized web application for that purpose, but always end up just creating a Google Doc or a wiki page, depending on what the company uses.
- hilverd 4y ago
  Yes -- you beat me to it :-). The built-in server is meant to be run only locally/offline (typically by a developer), just for making changes to a glossary. If you download and open the template (not one of the "full" examples) in a browser, then it tells you how: sed -n '/START OF editor.js$/,$p' glossary.html | FILE=glossary.html node Then you would host glossary.html (and maybe the CSS and JS if you don't want to point to the CDN) wherever you want, as it's just a static web page. I will make this clearer in the documentation -- thanks!

oefrha 4y ago

Maybe render the Jargon File in this format? Although it might be too large for a single page. http://www.catb.org/jargon/html/ http://www.catb.org/jargon/html/

hilverd 4y ago
Thanks, I had been looking for existing glossaries with permissive licenses to use as examples, and this one wasn't on my list yet. It does look way larger than any of the other examples. But it would be interesting to explore what sort of changes would be required to the template to keep it usable in practice.
- tutuca 4y ago
  The jargon file is trully an amazing relic. I love to get back to it from time to time. Your tools looks like an amazing overvamp for it! Great work!

1023bytes 4y ago

It might be possible to do this without the Node.js server by using the File System Access API https://web.dev/file-system-access/ https://web.dev/file-system-access/

hilverd 4y ago
Interesting, I hadn't considered that -- thanks. I was just having a look and it seems that right now, only Chrome and Edge (and Brave?) support that API. I'll keep an eye on it, because it doesn't seem like a viable option yet until Safari and Firefox also do.
- 1023bytes 4y ago
  It's possible to do this in Safari and Firefox as well, it's just that the experience isn't as seamless - instead of writing to the existing file a new copy will be downloaded. You can see this in the demo here: https://googlechromelabs.github.io/text-editor/ https://googlechromelabs.github.io/text-editor/

unraveller 4y ago

A similar project is imml, meant for textful landing pages, you can version the underlying imml file or the output html. https://leoncvlt.github.io/imml/ https://leoncvlt.github.io/imml/