From 785c4ed6bf2ec6539605b732c63569b0e3aab4d1 Mon Sep 17 00:00:00 2001 From: Retype GitHub Action Date: Mon, 25 Sep 2023 20:00:05 +0000 Subject: [PATCH] Refreshes Retype-generated documentation. Process triggered by patricklafrance. --- 404.html | 8 +- about/index.html | 8 +- backend/domain-event-propagation/index.html | 8 +- backend/mediatr-extensions/index.html | 8 +- backend/mongo-extensions/index.html | 8 +- frontend/foundry-cli/index.html | 8 +- frontend/hopper/index.html | 8 +- frontend/squide/index.html | 8 +- frontend/web-configs/index.html | 8 +- index.html | 8 +- joining-the-hub/index.html | 10 +-- resources/js/config.js | 2 +- resources/js/search.json | 2 +- sitemap.xml.gz | Bin 276 -> 277 bytes why-retype/index.html | 84 +++++++++++++++++--- 15 files changed, 119 insertions(+), 59 deletions(-) diff --git a/404.html b/404.html index 21a90dc..3043bf3 100644 --- a/404.html +++ b/404.html @@ -4,7 +4,7 @@ - + @@ -29,11 +29,11 @@ - + - + - + diff --git a/about/index.html b/about/index.html index 3f70376..c52634f 100644 --- a/about/index.html +++ b/about/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - + diff --git a/backend/domain-event-propagation/index.html b/backend/domain-event-propagation/index.html index 72887a8..4f3447c 100644 --- a/backend/domain-event-propagation/index.html +++ b/backend/domain-event-propagation/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/backend/mediatr-extensions/index.html b/backend/mediatr-extensions/index.html index 8715812..cdb1c36 100644 --- a/backend/mediatr-extensions/index.html +++ b/backend/mediatr-extensions/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/backend/mongo-extensions/index.html b/backend/mongo-extensions/index.html index aec276a..83d608b 100644 --- a/backend/mongo-extensions/index.html +++ b/backend/mongo-extensions/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/frontend/foundry-cli/index.html b/frontend/foundry-cli/index.html index a26ebd9..bdfe96c 100644 --- a/frontend/foundry-cli/index.html +++ b/frontend/foundry-cli/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/frontend/hopper/index.html b/frontend/hopper/index.html index 4b40e83..d627711 100644 --- a/frontend/hopper/index.html +++ b/frontend/hopper/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/frontend/squide/index.html b/frontend/squide/index.html index 6e6d311..9d8f759 100644 --- a/frontend/squide/index.html +++ b/frontend/squide/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/frontend/web-configs/index.html b/frontend/web-configs/index.html index 484ab3c..2f1cf3d 100644 --- a/frontend/web-configs/index.html +++ b/frontend/web-configs/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/index.html b/index.html index afb7134..ce03a32 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ - + @@ -34,11 +34,11 @@ - + - + - + diff --git a/joining-the-hub/index.html b/joining-the-hub/index.html index b5384cf..1768930 100644 --- a/joining-the-hub/index.html +++ b/joining-the-hub/index.html @@ -4,7 +4,7 @@ - + @@ -32,12 +32,12 @@ - + - + - - + + diff --git a/resources/js/config.js b/resources/js/config.js index 6c0894d..b044b93 100644 --- a/resources/js/config.js +++ b/resources/js/config.js @@ -1 +1 @@ -var __DOCS_CONFIG__ = {"id":"B7Uq0ZrTMkg16f0joUUCLuFuIK1nYNLlnP","key":"ADU7MBVk3BXLeylYtdsG+oqH9rXQAtPYRXXYokCJRIE.kKXiXL4sS3hw5vwIAwnOtybYAVHtyZJkStW/CLeJVgphIHzphorlKhPIHehYiyeRg2PDqdhPBBXtg+049EqYzQ.300025","base":"/wl-idp-docs-hub/","host":"gsoft-inc.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.5.0.748983896883","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"/","l":"Workleap Internal Developer Platform (IDP)","v":false},{"n":"frontend","l":"Frontend","c":false,"o":true,"i":[{"n":"foundry-cli","u":"https://github.com/gsoft-inc/wl-foundry-cli","l":"Foundry CLI"},{"n":"web-configs","u":"https://gsoft-inc.github.io/wl-web-configs","l":"Web configs"},{"n":"squide","u":"https://gsoft-inc.github.io/wl-squide","l":"Squide"},{"n":"hopper","u":"https://hopper.workleap.design","l":"Hopper"}],"s":""},{"n":"backend","l":"Backend","c":false,"o":true,"i":[{"n":"domain-event-propagation","u":"https://github.com/gsoft-inc/wl-domain-event-propagation","l":"Domain event propagation"},{"n":"mediatr-extensions","u":"https://github.com/gsoft-inc/wl-extensions-mediatr","l":"Mediatr extensions"},{"n":"mongo-extensions","u":"https://github.com/gsoft-inc/wl-extensions-mongo","l":"Mongo extensions"}],"s":""},{"n":"joining-the-hub","l":"Joining the hub","s":""},{"n":"why-retype","l":"Why Retype","s":""},{"n":"about","l":"About","v":false}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; +var __DOCS_CONFIG__ = {"id":"RzdC63aI26fPD/xjV16OtxMyeroi8WWmVD","key":"za19e4lcITslw0R3+q0erhix/03YlhR7Xkf0rbtfzwQ.J0bBuTW9LA+l2oMqN4ga8q/GhPGxSwHtxiPPAkrOM6tLqrc/Hc+mKM46Kj7zSqTE9MCPD64R3yzm6mIlaXtCqA.300101","base":"/wl-idp-docs-hub/","host":"gsoft-inc.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.5.0.748987201929","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"/","l":"Workleap Internal Developer Platform (IDP)","v":false},{"n":"frontend","l":"Frontend","c":false,"o":true,"i":[{"n":"foundry-cli","u":"https://github.com/gsoft-inc/wl-foundry-cli","l":"Foundry CLI"},{"n":"web-configs","u":"https://gsoft-inc.github.io/wl-web-configs","l":"Web configs"},{"n":"squide","u":"https://gsoft-inc.github.io/wl-squide","l":"Squide"},{"n":"hopper","u":"https://hopper.workleap.design","l":"Hopper"}],"s":""},{"n":"backend","l":"Backend","c":false,"o":true,"i":[{"n":"domain-event-propagation","u":"https://github.com/gsoft-inc/wl-domain-event-propagation","l":"Domain event propagation"},{"n":"mediatr-extensions","u":"https://github.com/gsoft-inc/wl-extensions-mediatr","l":"Mediatr extensions"},{"n":"mongo-extensions","u":"https://github.com/gsoft-inc/wl-extensions-mongo","l":"Mongo extensions"}],"s":""},{"n":"joining-the-hub","l":"Joining the hub","s":""},{"n":"why-retype","l":"Why Retype","s":""},{"n":"about","l":"About","v":false}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; diff --git a/resources/js/search.json b/resources/js/search.json index dff0392..b91fbbd 100644 --- a/resources/js/search.json +++ b/resources/js/search.json @@ -1 +1 @@ -[[{"i":"workleap-internal-developer-platform-idp","l":"Workleap Internal Developer Platform (IDP)","p":["Welcome to the documentation hub for Workleap IDP libraries. On this site, you'll discover a variety of libraries that collectively constitutes the internal developer platform for creating applications on the Workleap platform."]}],[],[],[],[],[],[],[],[{"l":"Joining the hub","p":["To include your library documentation in Workleap's IDP hub, follow these steps."]},{"l":"Create your Retype website","p":["First, navigate to the Retype getting started guide to set up a Retype website within your library repository."]},{"l":"Basic setup","p":["Then, open the retype.yml file located at the root of the repository and copy/paste the following basic configuration:","Finally, add the following script to your package.json file:","Please note that Retype is also compatible with .NET projects. If you are working on a .NET project, visit the Retype website for guidance on starting your Retype development."]},{"i":"try-it","l":"Try it \uD83D\uDE80","p":["Start your Retype site by executing the dev-docs script."]},{"i":"adhere-to-workleaps-conventions","l":"Adhere to Workleap's conventions","p":["The following conventions are optional but highly recommend to to guarantee a consistent and unified experience for Workleap's developers within the Workleap IDP hub."]},{"l":"Icons","p":["First, add Workleap's reversed bleu logo and favicon to the /docs/static folder:","Then, configure Retype to use the new assets by including the following configurations to your retype.yml file:"]},{"l":"Top bar links","p":["A link to a page listing your library releases.","A link to request a new feature for your library.","A link to the homepage of your Retype site.","A link to the library's packages.","A link to your library's bug tracker.","A link to your library's repository.","Description","Feature requests","Found a bug","GitHub (or another platform)","Home","Link","NPM / Nugget","Releases","Then, add the following links to the top nav bar of your Retype site:","Your Retype links configuration should closely resemble the following configurations"]},{"l":"Footer links","p":["Then, add the following links to the footer of your Retype site:","Link","Description","About","A link to an about page including meta informations about your library project ( example).","License","A link to the license of your library.","Your Retype footer links configuration should closely resemble the following configurations"]},{"l":"Retype navigation folder items","p":["We recommend adding an icon before each folder item of the main navigation (on the left):","Icon","Section","Use a rocket icon for a \"Getting Started\" section ( example).","Use a book icon for a \"Guides\" section ( example).","Use a gear icon for a \"Reference\" section ( example).","Use a question icon for a \"Troubleshooting\" section ( example).","Use a command-palette icon for a \"Sample\" section ( example)."]},{"l":"Include the shared CSS customizations file","p":["Our Retype websites share a CSS file that contains several customizations to enhance the default Retype style. To incorporate this file into your Retype site, follow these steps:"]},{"i":"create-the-_includesheadhtml-file","l":"Create the _includes/head.html file","p":["Create a _includes/head.html file within the /docs folder:"]},{"l":"Link the shared CSS file","p":["Then, open the newly created _includes/head.html file and copy/paste the following content:"]},{"l":"Activate pro features","p":["Workleap has acquired an Enterprise license for Retype, which you can locate the key in our secure Vault. To enable Retype's pro features, copy and paste the following configuration into your retype.yml file:"]},{"l":"Configure your Retype wallet","p":["Since we've added the following lines to your retype.yml file:","You can now develop a Retype site locally with the pro features without the need for a local Retype wallet. However, if you prefer to set up your local Retype wallet, follow these steps:","Locate the Retype license key in our secure Vault.","Utilize the Retype CLI to create your wallet."]},{"l":"Host your site on GitHub pages","p":["To use our Retype enterprise license, and for every hub features of Retype to work properly, the site must be hosted on the https://gsoft-inc.github.io domain. As this is a GitHub Pages domain, to join the hub, your Retype site must be deployed with GitHub Pages.","To configure your Retype site to be deployed with GitHub Pages, refer to the following guide.","You don't need to set the Retype Enterprise license key as it's already configured as an organization secret."]},{"l":"Add your site to the hub","p":["Send a PR to the wl-idp-docs-hub GitHub repository to add your site to the hub. Once merged, your site will be automatically added to the Workleap IDP hub!"]}],[{"l":"Why Retype over GitHub readme","p":["While GitHub README.md files are great, there are several compelling reasons to consider using a documentation platform like Retype:","Better Structuring: Retype simplifies the organization of documentation by allowing easy division into multiple files and provides an intuitive navigation system with a left sidebar for seamless browsing.","Automatic Table of Contents: Retype generates an in-page Table of Contents automatically from the page's headers, improving navigation within the documentation.","Powerful Search: Retype integrates advanced content search functionality, enabling developers to quickly locate the information they need.","Broken Link Detection: Retype's compilers swiftly identify any broken links (including anchors), ensuring that your documentation remains error-free.","Advanced Code Block Features: Retype's code blocks support features like line highlighting and optional titles, enhancing the presentation of code samples.","Rich components library: Retype offers out of the box a rich collection of markdown components that should meet the requirements of most documentation websites.","Outbound Links: Retype automatically identifies and manages external (outbound) links within the project, opening them in new tabs when clicked for a smoother user experience.","Multiple Layouts: Retype offers three distinct layouts out of the box: page, central, and blog, allowing flexibility in presentation.","Custom CSS: Retype allows to add custom global CSS and CSS classes to containers.","The Hub functionality: Retype's hub functionality enables the interlinking of multiple websites, facilitating seamless navigation between related resources.","By choosing Retype, we can take advantage of these features to enhance our documentation's organization, accessibility, and overall developers experience."]}],[{"l":"About","p":["To ask a question or propose an idea, feel free to start a new discussion on Github. If you found a bug, please open an issue on Github."]},{"l":"License","p":["See the LICENSE on Github."]}]] \ No newline at end of file +[[{"i":"workleap-internal-developer-platform-idp","l":"Workleap Internal Developer Platform (IDP)","p":["Welcome to the documentation hub for Workleap IDP libraries. On this site, you'll discover a variety of libraries that collectively constitutes the internal developer platform for creating applications on the Workleap platform."]}],[],[],[],[],[],[],[],[{"l":"Joining the hub","p":["To include your library documentation in Workleap's IDP hub, follow these steps."]},{"l":"Create your Retype website","p":["First, navigate to the Retype getting started guide to set up a Retype website within your library repository."]},{"l":"Basic setup","p":["Then, open the retype.yml file located at the root of the repository and copy/paste the following basic configuration:","Finally, add the following script to your package.json file:","Please note that Retype is also compatible with .NET projects. If you are working on a .NET project, visit the Retype website for guidance on starting your Retype development."]},{"i":"try-it","l":"Try it \uD83D\uDE80","p":["Start your Retype site by executing the dev-docs script."]},{"i":"adhere-to-workleaps-conventions","l":"Adhere to Workleap's conventions","p":["The following conventions are optional but highly recommend to to guarantee a consistent and unified experience for Workleap's developers within the Workleap IDP hub."]},{"l":"Icons","p":["First, add Workleap's reversed bleu logo and favicon to the /docs/static folder:","Then, configure Retype to use the new assets by including the following configurations to your retype.yml file:"]},{"l":"Top bar links","p":["A link to a page listing your library releases.","A link to request a new feature for your library.","A link to the homepage of your Retype site.","A link to the library's packages.","A link to your library's bug tracker.","A link to your library's repository.","Description","Feature requests","Found a bug","GitHub (or another platform)","Home","Link","NPM / Nugget","Releases","Then, add the following links to the top nav bar of your Retype site:","Your Retype links configuration should closely resemble the following configurations"]},{"l":"Footer links","p":["Then, add the following links to the footer of your Retype site:","Link","Description","About","A link to an about page including meta informations about your library project ( example).","License","A link to the license of your library.","Your Retype footer links configuration should closely resemble the following configurations"]},{"l":"Retype navigation folder items","p":["We recommend adding an icon before each folder item of the main navigation (on the left):","Icon","Section","Use a rocket icon for a \"Getting Started\" section ( example).","Use a book icon for a \"Guides\" section ( example).","Use a gear icon for a \"Reference\" section ( example).","Use a question icon for a \"Troubleshooting\" section ( example).","Use a command-palette icon for a \"Sample\" section ( example)."]},{"l":"Include the shared CSS customizations file","p":["Our Retype websites share a CSS file that contains several customizations to enhance the default Retype style. To incorporate this file into your Retype site, follow these steps:"]},{"i":"create-the-_includesheadhtml-file","l":"Create the _includes/head.html file","p":["Create a _includes/head.html file within the /docs folder:"]},{"l":"Link the shared CSS file","p":["Then, open the newly created _includes/head.html file and copy/paste the following content:"]},{"l":"Activate pro features","p":["Workleap has acquired an Enterprise license for Retype, which you can locate the key in our secure Vault. To enable Retype's pro features, copy and paste the following configuration into your retype.yml file:"]},{"l":"Configure your Retype wallet","p":["Since we've added the following lines to your retype.yml file:","You can now develop a Retype site locally with the pro features without the need for a local Retype wallet. However, if you prefer to set up your local Retype wallet, follow these steps:","Locate the Retype license key in our secure Vault.","Utilize the Retype CLI to create your wallet."]},{"l":"Host your site on GitHub pages","p":["To use our Retype enterprise license, and for every hub features of Retype to work properly, the site must be hosted on the https://gsoft-inc.github.io domain. As this is a GitHub Pages domain, to join the hub, your Retype site must be deployed with GitHub Pages.","To configure your Retype site to be deployed with GitHub Pages, refer to the following guide.","You don't need to set the Retype Enterprise license key as it's already configured as an organization secret."]},{"l":"Add your site to the hub","p":["Send a PR to the wl-idp-docs-hub GitHub repository to add your site to the hub. Once merged, your site will be automatically added to the Workleap IDP hub!"]}],[{"l":"Why Retype"},{"l":"Comparison with GitHub readme files","p":["While GitHub README.md files are great, there are several compelling reasons to consider using a documentation platform like Retype:","Better Structuring: Retype simplifies the organization of documentation by allowing easy division into multiple files and provides an intuitive navigation system with a left sidebar for seamless browsing.","Automatic Table of Contents: Retype generates an in-page Table of Contents automatically from the page's headers, improving navigation within the documentation.","Powerful Search: Retype integrates advanced content search functionality, enabling developers to quickly locate the information they need.","Broken Link Detection: Retype's compilers swiftly identify any broken links (including anchors), ensuring that your documentation remains error-free.","Advanced Code Block Features: Retype's code blocks support features like line highlighting and optional titles, enhancing the presentation of code samples.","Rich components collection: Retype offers out of the box a rich collection of markdown components that should meet the requirements of most documentation websites.","Outbound Links: Retype automatically identifies and manages external (outbound) links within the project, opening them in new tabs when clicked for a smoother user experience.","Multiple Layouts: Retype offers three distinct layouts out of the box: page, central, and blog, allowing flexibility in presentation.","Custom CSS: Retype allows to add custom global CSS and CSS classes to containers.","The Hub functionality: Retype's hub functionality enables the interlinking of multiple websites, facilitating seamless navigation between related resources.","By choosing Retype, we can take advantage of these features to enhance our documentation's organization, accessibility, and overall developers experience."]},{"l":"Comparison with other documentation platforms","p":["When considering documentation platforms, it's essential to explore alternatives to Retype. Several options exist, including SaaS-based solutions like Gitbook and self-hosted options like Docusaurus, Rspress, or even creating a custom website using Next.js."]},{"l":"SaaS-Based Platforms","p":["SaaS-based platforms like Gitbook offer convenience but can fall short in terms of customization and often come with complex pricing structures, particularly when managing a collection of libraries like Workleap's IDP."]},{"l":"Solution-Based Platforms","p":["Solution-based platforms like Docusaurus can match Retype's feature set but tend to have a higher entry barrier. Each website created with Docusaurus is entirely custom and involves frontend tooling. The entry barrier increases significantly because developers must possess knowledge of how frontend tools operate and how to build a React application.","One of Retype's strengths lies in its balance between customization and ease of entry. It provides just enough customization to create rich and personalized documentation while maintaining a very low entry barrier. Basic knowledge of markdown is all that's needed to get started.","High-level solution structure of a Docusaurus website:","High-level solution structure of a Retype website:","In summary, platforms like Docusaurus demand frontend expertise to write documentation effectively, while Retype only requires a basic understanding of markdown. Retype functions as a command-line interface (CLI) that compiles markdown files into a website, making it adaptable even within a .NET repository since it supports the .NET platform."]}],[{"l":"About","p":["To ask a question or propose an idea, feel free to start a new discussion on Github. If you found a bug, please open an issue on Github."]},{"l":"License","p":["See the LICENSE on Github."]}]] \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index c4e1e7ebfb27ca1b6659d4860e09f935c3e122e4..7e1c400ad58b6aacbad4ee133dee0f81aa9da671 100644 GIT binary patch literal 277 zcmV+w0qXuAiwFP!000001FVwIZiFBZ#_v9b;STsGZi`X&)+gA#^yVrRHVOvDvcCPI zYnn9attKSH%zR(?F`4T87>D>AptS%Ljf(XC76v9h`tTh_$Pc z1ei)nz4yc^5MwhrVr)-cD?{SwUZe?O=;bLN62{?|)90HfWsK3Si+B{r>q~14x52c0 z)w^Kmo%sT+bW3^#a=sB|s2{NECfu3U;ZUL#T^+l(aWI;WXGxahgyF2Xq^vB$IeiA* z-hF8&tBh5!@bLSJ{$wi*-D&^*G(l6<}wx&iIVJMZRwVgJ7joz-W_yt`=Qq6Ag64DqpzD5dQ zDk%*i5U)Xw&E$!7J@u`Mg{OOyGQ!b=Denr#;TIW-jmbFYbekfPr0IIny2jmLTe0SS z1bS~j0Bh5dUW1x%L|YmLth)(!w)Hr+Xhm0IXB!Wr?L^M<0yB>D^EKloJC!H?9&`Kj zk)52jPQxPN?JN3Itul1C`G?h~)h0eB1|^TNWaPOxUNfi#I|<7qk1#wx9dFp&> - + - Why Retype over GitHub readme - + Why Retype + @@ -20,23 +20,23 @@ - + - + - + - + - + @@ -195,12 +195,18 @@
- +

- # - Why Retype over GitHub readme + # + Why Retype

+ +

+ # + Comparison with GitHub readme files +

+

While GitHub README.md files are great, there are several compelling reasons to consider using a documentation platform like Retype:

  1. Better Structuring: Retype simplifies the organization of documentation by allowing easy division into multiple files and provides an intuitive navigation system with a left sidebar for seamless browsing.

    @@ -213,7 +219,7 @@

  2. Advanced Code Block Features: Retype's code blocks support features like line highlighting and optional titles, enhancing the presentation of code samples.

    3. -

  3. Rich components library: Retype offers out of the box a rich collection of markdown components that should meet the requirements of most documentation websites.

    +

  4. Rich components collection: Retype offers out of the box a rich collection of markdown components that should meet the requirements of most documentation websites.

  5. Outbound Links: Retype automatically identifies and manages external (outbound) links within the project, opening them in new tabs when clicked for a smoother user experience.

    6. @@ -225,6 +231,60 @@

By choosing Retype, we can take advantage of these features to enhance our documentation's organization, accessibility, and overall developers experience.

+ +

+ # + Comparison with other documentation platforms +

+ +

When considering documentation platforms, it's essential to explore alternatives to Retype. Several options exist, including SaaS-based solutions like Gitbook and self-hosted options like Docusaurus, Rspress, or even creating a custom website using Next.js.

+ +

+ # + SaaS-Based Platforms +

+ +

SaaS-based platforms like Gitbook offer convenience but can fall short in terms of customization and often come with complex pricing structures, particularly when managing a collection of libraries like Workleap's IDP.

+ +

+ # + Solution-Based Platforms +

+ +

Solution-based platforms like Docusaurus can match Retype's feature set but tend to have a higher entry barrier. Each website created with Docusaurus is entirely custom and involves frontend tooling. The entry barrier increases significantly because developers must possess knowledge of how frontend tools operate and how to build a React application.

+

One of Retype's strengths lies in its balance between customization and ease of entry. It provides just enough customization to create rich and personalized documentation while maintaining a very low entry barrier. Basic knowledge of markdown is all that's needed to get started.

+

High-level solution structure of a Docusaurus website:

+
+
root
+├── docs
+├──── Folder-1
+├─────── page1.md
+├── src
+├──── components
+├─────── Tab.tsx
+├─────── HomePageItem.tsx
+├──── css
+├──── pages
+├─────── index.tsx
+├─────── Home.tsx
+├──── static
+├── .gitignore
+├── babel.config.js
+├── docusaurus.config.js
+├── sidebars.js
+├── tsconfig.ts
+├── package.json
+
+

High-level solution structure of a Retype website:

+
+
root
+├── docs
+├──── Folder-1
+├─────── page1.md
+├── retype.yml
+├── package.json
+
+

In summary, platforms like Docusaurus demand frontend expertise to write documentation effectively, while Retype only requires a basic understanding of markdown. Retype functions as a command-line interface (CLI) that compiles markdown files into a website, making it adaptable even within a .NET repository since it supports the .NET platform.