Package: discourse-docsify
discourse-docsifyFlask extension to source data fromdiscourseforum posts into adocsify(documentation) website.This allows you to leverage docsify's features while still benefiting from discourse's forum nature: beautiful documentation anyone within your community may expand on and contribute to.This project was inspired by thiscanonicalwebeteam's repo.SetupInstall withpipinstalldiscourse-docsifyYou can initialize the extension directly:fromflaskimportFlaskfromdiscourse_docsifyimportDocsapp=Flask(__name__)# for more config options and additional parameters see belowdocs=Docs(app,config={'DOCS_HOMEPAGE_TITLE':'My Documentation Website','DOCS_DISCOURSE_API_USERNAME':'...','DOCS_DISCOURSE_API_KEY':'...','DOCS_DISCOURSE_BASE_URL':'...','DOCS_DISCOURSE_INDEX_TOPIC_ID':'...',})or by doingfromflaskimportFlaskfromdiscourse_docsifyimportDocs# for more config options and additional parameters see belowdocs=Docs(config={'DOCS_HOMEPAGE_TITLE':'My Documentation Website','DOCS_DISCOURSE_API_USERNAME':'...','DOCS_DISCOURSE_API_KEY':'...','DOCS_DISCOURSE_BASE_URL':'...','DOCS_DISCOURSE_INDEX_TOPIC_ID':'...',})app=Flask(__name__)docs.init_app(app)No plugin needs to be installed on discourse, you simply need a valid API key.Index topicThe index topic contains the homepage content, a list of urls mappings to translate documentation paths into forum topics and the documentation sidebar.In this topic, # headings specify the start of a section. Each of the contents described above corresponds to a specific section.
Here is the format the topic should have:# HomepageWelcome to my Documentation!# URLs[details=Mapping table]
| topic | path |
| -- | -- |
| forum-url/t/general-handbook/5258 | /general-handbook |
| forum-url/t/how-to-install/5256  | /installation |
| forum-url/t/developer-api-specs/5259 | /api |
[/details]# Navigation[details=Navigation]
| level | path | navlink |
| -- | -- | -- |
| 1 |  | Handbooks |
| 2 | general-handbook | General Handbook |
| 1 | installation | Installation Instructions |
| 1 | api | Dev API |

[/details]The names of the sections are important (Homepage,URLsandNavigation).In the URLs table, we have pairs oftopic(forum link) andpath(the documentation url path).In the Navigation table, thelevelsets the indentation in the sidebar (meaning a level 2 item will be inside the level 1 item immediately above it),pathis a path from the URLs table (or empty, if you want a linkless category) andnavlinkis the actual text in this sidebar navigation item.Features and DescriptionDiscourse-Docsify will create a blueprint at the/docsurl prefix (can be changed through the config) which will serve the files requested by docsify by fetching the forum content for the topic associated with each path.The original topic markdown is used (and not the discourse html generated output) so you may use any docsify compatible markdown.A caching feature is also included to speed up loading times (as querying the forum for every request can be quite slow) which may either be through a simple python dictionary or throughredis.Optionally, one function to be run before content is served can also be passed to the Docs object.The pre_content functionDocsaccepts a third parameter: the pre_content function, a function run before each documentation request and that you may use to, for example, restrict access based on some sort of authentication:defdocs_auth_validation(path):if'profile'notinsession:returnredirect('/login')ifnotsession['profile']['admin']:returnabort(403,'Only admins may view this page.')docs=Docs(app,{...},docs_auth_validation)This function has one argument: the current request's path.Configuration referenceSetting nameDefaultDescriptionDOCS_URL_PREFIX/docsThe URL prefix for the blueprint that will be serving the docs.DOCS_HOMEPAGE_TITLEDocumentationHomepage titleDOCS_INDEX_PATHThere is a defaultindex.htmlfile with a simple docsify example, which you can replace by giving the path to your own file here.DOCS_TEMPLATE_PATHThere is a default template to generate the documentation content (which appends edit buttons with a forum link and last updated time) but you can replace it with your own by entering its path here.DOCS_HUMANIZE_LOCALEhumanizeis used to generate the "last updated" strings (2 hours ago, a month ago, etc). If you want to change the language used, enter a locale name here. Example:ru_RUfor russian.DOCS_CACHE_TIMEOUT60 * 10Number of seconds for which to cache each page's content.DOCS_CACHE_TYPEmemoryeithermemory(uses a simple python dictionary) orredisDOCS_CACHE_REDIS_CONN{}if using redis, the redis connection arguments,passed to the Redis constructor.DOCS_CACHE_REDIS_PREFIXdiscourse_docsify_docs_Prefix to use for redis cachingDOCS_DISCOURSE_API_USERNAMEDiscourse API username. Needed to fetch forum content.DOCS_DISCOURSE_API_KEYDiscourse API key. Needed to fetch forum content.DOCS_DISCOURSE_BASE_URLThe discourse (forum) main url.DOCS_DISCOURSE_INDEX_TOPIC_IDThe ID of the index topic (the number at the end of the topic url).