GH pages

[hi5]

Not sure where the GH pages is going but at the moment it seems to be a duplication of markdown content, shouldn't it therefore be more productive to write a script that converts the readme.md to HTML so you can simply update (sections of) HTML pages?

• AHK solution for parsing Markdown: https://github.com/fincs/GenDocs/blob/master/Lib/Markdown2HTML.ahk (also requires StrStartsWith from the same LIB folder)
• Third party solutions
  • https://github.com/jgm/pandoc/
  • https://github.com/fletcher/MultiMarkdown

[joedf]

Well ghpages supports Jekyll.... Maybe that would be simpler?
https://help.github.com/articles/using-jekyll-with-pages/

[G33kDude]

... It is an autohotkey script for converting the readme into html pages.

https://github.com/ahkscript/awesome-AutoHotkey/blob/gh-pages/AAH2html.ahk

Edit: Good to see fincs has done a proper markdown interpreter though, I was just cheating at it with a few simple regexes. I'll see if I can add it in

[hi5]

OK missed that script, just saw the HTML pages with similar content to the readme.md

fincs function isn't a "complete" markdown solution but supports the basics...

[G33kDude]

It wasn't originally an AutoHotkey script, but it quickly became one once I saw there was already a pretty decent list I could contribute to.

Edit: Originally I wanted to contribute to the wiki, but they don't allow new people to register (probably due to the large amount of spambots registering accounts). I decided to start my own project then, after looking around, so I did. I didn't see this one until later

[rshipp]

Wow, that wiki list has a ton of scripts. Who's in charge of that, is it not just TLM or tank?

[G33kDude]

Not sure, but @joedf has an account on it

[G33kDude]

gh-pages currently doesn't display author information or if an item is discontinued. I'll need to fix this eventually I think.

[hoppfrosch]

gh-pages seem to be outdated:

• not all items from readme.md are visible
• the document structure differs from readme.md (no level 4 headings are shown ...)

BTW: Whats the suggested way to regenerate gh-pages after editing readme.md?

[G33kDude]

You merge the main branch into the gh-pages branch, then run converter script. Afterwards, you verify in the diff that nothing went wrong. After you've verified, you push the gh-pages branch.

Want me to get that, or would you like to try?

Also it's very possible that it's missing some sections, so we might need to update the converter.

[joedf]

What if we used Jekyll or something

[G33kDude]

Have you ever tried to get Jekyll up and running on a windows desktop? It's no small feat, in my experience. Also, what does Jekyll bring to the table that we can't already do?

[joedf]

So that's a no? But, we don't need to install Jekyll on our own computer. :/

[G33kDude]

You don't have to install Jekyll, but it's a lot harder to develop for something when you can review changes after pushing to somewhere. Also, I'm not sure Jekyll offers the functionality that we're using (building a site from a single md file). I thought it was a more structured thing, requiring specifically named, written, and organized files. If we do go with Jekyll, it'd mean we would need to manage/write the gh-pages branch separately from the main branch.

[joedf]

Ok, :P

[hoppfrosch]

Same experience here: jekyll is hard to install on windows - and developing without possibility to check locally is pretty uncool ...

@G33kDude: I'll try to merge gh_pages and running rhe converter script. In case of failure or problems I'll be right back ;-)

---

Edit: gh_pages succesfully rebuild and published on github

[joedf]

ok, cool.

[hoppfrosch]

Current gh_pages misses a lot of entries from readme.md. Either the gh_pages generator (AAH2html.ahk) has to be enhanced a lot and/or the Contributing.md file has to be adapted accordingly.

What currently fails with AAH2html.ahk:

• markdown is not rendered: text decorations in markdown like italic (WORD) or bold (WORD) are not translated correctly into corresponding HTML-Tags
• a lot of entries within readme.md are currently lost after conversion into gh_pages, as the entries are not according contributing.md. Most failures are caused by missing the hyphen after the script link. For example *Eval by fincs (discontinued) fails because the hyphen before "by" is missing ...
• the structure of readme.md, using section and subsections is lost, as subsections are not considered ....

There should by a guideline within contributing.md where to put the author and the state of the script.

[vasili111]

There should by a guideline within contributing.md where to put the author and the state of the script.

Agree with you @hoppfrosch and made #42 to discuss that.



About github pages: I am not good at html and how gh works so I can't say too much about that topic. I will agree what community decides.

[joedf]

Thoughts? uses Strapdown.js (marked.js as the parser) + strapdown-topbar.js (by me 😄 )
Hosted Example: http://ahkscript.org/joedf/awesome-autohotkey/
Branch: https://github.com/ahkscript/awesome-AutoHotkey/tree/markdown-web-test-1

[hoppfrosch]

Generally like it, as it's preserving the structure of the main page and renders markdown almost correctly

A few things:

• The gitter chat badge on the very top of the page is not rendered correctly
• Styling: Headlines do not differ enough IMHO (You nearly cannot distinguish optically, whats a h1, h2, h3 ....
• Table of contents does not preserve the hierarchical structure of TOC in Readme.md - it's simply converted in a plain list without hierarchy
• Menubar: Contents Menu does not preserve the hierarchical structure of TOC in Readme.md. Maybe use of submenues make sense here .....

[joedf]

Thanks :)
Yes, there's a few issues with the parser. I don't think it actually supports a " Table of contents". The menubar I could fix. As for the rest, I'll just have to adjust the CSS a little bit, and fix the gitter badge.

[hoppfrosch]

@joedf: did you work on this recently?

My suggestion: as long as there is no good solution available (currently AAH2html.ahk is outdated and does not convert markup syntax correctly into html (i.e. bold, italic ...)) its not possible to generate good gh-pages. At the moment the gh-pages are terribly outdated.
Therefore my suggestion: remove/disable gh-pages until we have a relyable converter

My personal opinion is that we don't need the gh-pages at all - the gh-pages don't add any additional infromation which isn't available within README.md; it's just a different visual representation. Other awesome lists (like https://github.com/sorrycc/awesome-javascript also lack gh-pages. Therefore the gh-pages should be removed finally IMHO.

[joedf]

@hoppfrosch
No, I have not.
I imagine that you are right, I am not sure why we had gh-pages.

[MasterFocus]

My 2 cents (without actually reading the whole thing): I don't think we need an HTML version, as we can simply point people to the awesome-autohotkey README file in GitHub.

[hoppfrosch]

As there were no objections and no reasons to keep the gh-pages, gh-pages are gonna be removed. Also the scripts to generate the gh-pages are removed as they are obsolete.

[vasili111]

I agree that removing gh-pages is good idea. I don't see the need in two formats, especially when github format is pretty good.