Wyświetlanie PDF'ów w formie strony internetowej

[czlowiek488]

W związku z komentarzem #33 (comment) stworzyłem issue na ramach którego możemy porozmawiać na temat pomysłu dotyczącego wyświetlania pdf'ów w przyjaznej dla użytkownika końcowego formie.

Kontynuując wątek moim zdaniem aktualnie jest sens żeby wyświetlać PDF'y w formie strony internetowej.
Jednak na samym początku proponowałbym wyświetlanie tylko tych z brancha master przy użyciu gotowej biblioteki.
W taki sposób w dość szybkim czasie można stworzyć aplikację np. z wykorzystaniem proponowanych w w/w komentarzu github pages.
Jeżeli chodzi o rozwiązania technologiczne to proponuję to co jest standardem w obszarze aplikacji frontendowych w Polsce - React, dzięki temu będzie można korzystać z wielu gotowych bibliotek np. do wyświetlania pdf'ów - https://www.npmjs.com/package/react-pdf, a sam projekt będzie gotowy do przyszłego rozwoju i ewentualnych modyfikacji.

Osobiście na ten moment wyobrażam sobie stronę na której nie ma absolutnie nic innego oprócz samej przeglądarki pdf'ów.
Część aplikacji jest już tak naprawdę gotowe z racji wielu przykładów użycia w/w biblioteki - https://codesandbox.io/s/react-pdf-z6jh4

Do dodania zostałyby

1. Przyciski pozwalające na przeglądanie stron pdf'a
2. Przyciski pozwalające na zmianę załadowanego pliku
3. Ładowanie PDF'ów przez link z hostingu np. AWS S3
4. Dodanie skryptu w github actions wysyłającego PDF do AWS S3

[ctomczyk]

Moim zdaniem React framework tutaj jest za dużym kalibrem. Zwyczajna konwersja Markdown do HMTL-a powinna być całkowicie wystarczająca. Nie wspominając już o tym, że publikowany dokument powinien być dostępny dla każdego. Włączając w to osoby niepełnosprawne.

[piotrminkina]

Mkdocs ze skórką material się tu powinien sprawdzić. Ma wyszukiwarkę na bazie zindeksowanych fraz. Z pluginem "with pdf" daje możliwość konwersji do PDFów, w stylu material, a sam link do PDFa jest dołączony do wygenerowanej strony w HTMLu. Z pluginem "mike" daje możliwość wersjonowania dokumentacji i przełączania się między wersjami.

[ctomczyk]

@piotrminkina Czy generowany HTML spełnia standardy WCAG 2.1 AA?

[czlowiek488]

@ctomczyk Zgadzam się że to duży kaliber, aczkolwiek nigdy nie wiadomo co się będzie działo w przyszłości. Nie naciskam na reacta, inne opcje też mogą być w porządku.
Z drugiej strony z reacta jest gotowiec i byłbym w stanie całość postawić w 2-3h.
Z kolei utrzymywanie dwóch generatorów (MD -> PDF, MD -> HTML) może być kłopotliwe jak się różnie będą rzeczy wyświetlać.
Widzę opcje na embedowanie PDF w HTML https://www.geeksforgeeks.org/how-to-embed-pdf-file-using-html/ mam wrażenie że to może być coś co warto rozważyć.
Pytanie tylko co w jaki sposób będą wybierane pliki? Aktualnie jest ich kilka i trzeba by w jakiś sposób obsłużyć ich zmienianie.

[czlowiek488]

@piotrminkina No wygląda to fajnie https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs, jak obsługuje generowanie PDF'ów to wypadałoby też wymienić to co aktualnie jest w github actions.

[ctomczyk]

@czlowiek488

Zgadzam się że to duży kaliber, aczkolwiek nigdy nie wiadomo co się będzie działo w przyszłości. Nie naciskam na reacta, inne opcje też mogą być w porządku.

Moje zdanie jest takie, by trzymać repozytorium w bardzo prostej formie. Tutaj bardziej chodzi o to, aby każdy mógł łatwo zgłaszać sugestie, a także by build był efektywny:

1. Zgłoszenie
2. Merge
3. Build
4. Deploy

Ponadto, React i inne SPA frameworki, produkują zawartość niekoniecznie przyjazne wyszukiwarkom. Nie mówiąc o tym, że jest duża szansa, że pewna grupa osób będzie dyskryminowana w dostępnie, np. niewidomi.

Z kolei utrzymywanie dwóch generatorów (MD -> PDF, MD -> HTML) może być kłopotliwe jak się różnie będą rzeczy wyświetlać.

Generator można łatwo zmienić. Framework - jak "wdepniesz" to ciężko z niego wyjść.

Widzę opcje na embedowanie PDF w HTML https://www.geeksforgeeks.org/how-to-embed-pdf-file-using-html/ mam wrażenie że to może być coś co warto rozważyć.

Albo:
https://www.sitelint.com/blog/how-to-embed-a-pdf-in-html-without-downloading-it/

Pytanie tylko co w jaki sposób będą wybierane pliki? Aktualnie jest ich kilka i trzeba by w jakiś sposób obsłużyć ich zmienianie.

GitHub Actions: https://github.com/features/actions pozwoli ogarnąć automatyczny deployment wraz z konwersją MD na PDF. Jeśli będą różnice to się znajdzie alternatywne rozwiązanie.

[piotrminkina]

@ctomczyk Czy spełnia standard, to nie wiem, chociaż na szybko znalazłem, że są jakieś zamknięte zgłoszenia dotyczące poprawy dostępności, np.:

• Slightly increase contrast for footer text to meet WCAG guidelines squidfunk/mkdocs-material#4823
• Accessibility Part 2 squidfunk/mkdocs-material#1392

Ogólnie w tej materii trzebaby patrzeć na to co potrafi sam material, a nie stricte mkdocs. Cała ta strona została wygenerowana wparze mkdocs + material: https://squidfunk.github.io/mkdocs-material/

[ctomczyk]

@piotrminkina Warto poeksperymentować. Jak nie będzie działać dobrze, to wówczas podejmie się dyskusję i dalsze kroki.

[piotrminkina]

Opublikowałem część możliwości tego narzędzia w komentarzu: #109 (comment)

Tu dodam jak wygląda przykładowa strona główna:

Material daje przełączania między dwoma wybranymi schematami kolorów:

[ctomczyk]

@piotrminkina Na pierwszy rzut oka wygląda dobrze. Niemniej jednak wiadomo, że z biegiem czasu będzie wszystko ewoluować.

[Deathis]

Myślę, że dobrym rozwiązaniem byłoby pozostawienie samych plików źródłowych w projekcie, a konwersje do innych formatów takich jak PDF, HTML może odbywać się w tle w formie releasów, deployu bez udziału użytkownika. Nie trzeba dodawać do projektu plików reacta czy plików innego frameworka. Te frameworki tworzą zestaw plików wynikowych i nie ma takiej potrzeby umieszczania ich w źródle tego projektu.