Open czlowiek488 opened 1 year ago
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.
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.
@piotrminkina Czy generowany HTML spełnia standardy WCAG 2.1 AA?
@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.
@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.
@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:
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.
@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.:
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/
@piotrminkina Warto poeksperymentować. Jak nie będzie działać dobrze, to wówczas podejmie się dyskusję i dalsze kroki.
Opublikowałem część możliwości tego narzędzia w komentarzu: https://github.com/ProjektyUstaw/Ustawy-o-PIT/issues/109#issuecomment-1547830717
Tu dodam jak wygląda przykładowa strona główna:
Material daje przełączania między dwoma wybranymi schematami kolorów:
@piotrminkina Na pierwszy rzut oka wygląda dobrze. Niemniej jednak wiadomo, że z biegiem czasu będzie wszystko ewoluować.
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.
W związku z komentarzem https://github.com/ProjektyUstaw/Ustawy-o-PIT/pull/33#issuecomment-1547675833 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