{"id":13433693,"url":"https://github.com/jordwalke/paradoc","last_synced_at":"2025-08-01T07:34:32.295Z","repository":{"id":48764270,"uuid":"333646898","full_name":"jordwalke/paradoc","owner":"jordwalke","description":"One Click Docs","archived":false,"fork":false,"pushed_at":"2021-07-13T01:38:30.000Z","size":8398,"stargazers_count":181,"open_issues_count":7,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-29T03:05:38.380Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jordwalke.png","metadata":{"files":{"readme":"README.html","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-28T04:38:56.000Z","updated_at":"2025-05-02T18:12:38.000Z","dependencies_parsed_at":"2022-08-30T12:30:49.139Z","dependency_job_id":null,"html_url":"https://github.com/jordwalke/paradoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jordwalke/paradoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jordwalke%2Fparadoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jordwalke%2Fparadoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jordwalke%2Fparadoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jordwalke%2Fparadoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jordwalke","download_url":"https://codeload.github.com/jordwalke/paradoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jordwalke%2Fparadoc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268185560,"owners_count":24209392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T02:01:33.326Z","updated_at":"2025-08-01T07:34:32.272Z","avatar_url":"https://github.com/jordwalke.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[ vim: set filetype=Markdown: ]: # (\u003cstyle type=\"text/css\"\u003ebody {visibility: hidden} \u003c/style\u003e)\n[ vim: set filetype=Markdown: ]: # (\u003cmeta charset=\"utf-8\"\u003e)\n[ vim: set filetype=Markdown: ]: # (\u003cscript src=\"site/Paradoc.js\"\u003e \u003c/script\u003e)\n[//]: # (---)\n[//]: # (title: Paradoc)\n[//]: # (subtitle: Instantly write, deploy, and enjoy docs)\n[//]: # (description: Paradoc - Easy Markdown Pages)\n[//]: # (nextPage: configuring-pages)\n[//]: # (siteTemplate: siteTemplate.html)\n[//]: # (---)\n\n\n- **No servers, No build**\n\n- **Deployable Sites Right [From Chrome](#easy-optimizing-with-chrome)**\n\n- **Markdown [features](#markdown-features) for developers. [Offline Search](#search-features).**\n\n### Workflow\n\n- Write regular markdown in `.html` files with a single script tag at the top.\n- Everything after the script tag is regular markdown.\n\n\n```markdown\n\u003cscript src=\"site/Paradoc.js\"\u003e\u003c/script\u003e\nEverything _after_ the first line is\nplain **markdown**.\n```\n\n\u003ccontinueRight/\u003e\n\n- Double click the `.html` file to turn your markdown into a beautiful webpage.\n\n- To make changes, just edit the contents of the file and reload the browser.\n\n\n### Try It Out\n\n[The Paradoc landing page](https://jordwalke.github.io/paradoc/README.html) was\ncreated from the Paradoc repo's main `README.html` markdown file. Clone this\nrepo and double click `README.html` to turn it into this webpage.\n\n1. `git clone git@github.com:jordwalke/paradoc.git`\n2. Double click `README.html`\n\n\n\n\u003e Note: The script include in _this_ `README.html` looks complicated because it\n\u003e uses [Advanced Features](#integration-github-readme) that allows a single\n\u003e `README.html` to act as a website, _and_ a Github README, always kept in\n\u003e sync.  Your files will probably use the [very simple script\n\u003e include](#workflow?txt=41316212813224330877011010h0) already discussed.\n\n\n### Looks\n\n\n#### Split View\n\nParadoc comes with a UI theme that supports a left/right responsive split\nlayout.  As you increase the window size, code samples and block quotes are\nsplit into a right hand column.\n\n\u003e Note: The style for this split view comes from Paradoc's use of\n\u003e [flatdoc](https://ricostacruz.com/flatdoc/), but has been heavily modified.\n\u003e The split view can be disabled in your\n\u003e [`siteTemplate`](configuring-pages.html#the-site-template).\n\nSome of the additional [markdown extension features](#markdown-extensions)\ncontrol the behavior of this split view.\n\n\n### Markdown Extensions\n\nParadoc supports extended markdown features specified in [Github Flavored\nmarkdown](https://github.github.com/gfm/), and also supports some additional\nParadoc specific features.\n\n\n#### Code highlighting\n\nWith [GitHub Flavored Markdown][fences] you can use Markdown code fences to\nmake syntax-highlighted text. In Paradoc, codeblocks will be rendered in the right column\nof the [split view](#looks-split-view) if the window is sufficiently wide.\n\n~~~markdown\n```javascript\nconsole.log(\"This\", \"is a log\");\n```\n~~~\n\n\n#### Blockquotes\n\nBlockquotes also show up in the right hand column when the window is\nsufficiently large. This is useful for providing extra information or non-code\nexamples that move out of the way of the main document.\n\n\u003e Blockquotes are blocks that begin with `\u003e`.\n\n#### Smart quotes\n\nSingle quotes, double quotes, and double-hyphens are replaced to their\n\"typographically-accurate\" equivalent. This does not apply to `\u003ccode\u003e` and\n`\u003cpre\u003e` blocks.\n\n\u003e \"Check out this quote here. Look how how correct the quotes are\"\n\u003e --me\n\n\n#### `\u003ccontinueRight/\u003e`\n\nParadoc adds an additional feature that allows a right column element to continue\nflowing.\n\n\u003e This blockquote comes immediately after the text\n\u003e _\"Paradoc adds an additional feature that allows a right column element to\n\u003e continue flowing\"_\n\u003e but notice how this blockquote also continues to \"flow\" into the list that\n\u003e comes after it? This is important for creating a better balance of left and\n\u003e right content. Doing so requires the author to opt into having particular\n\u003e blockquote/code blocks flow into subsequent left content when it makes sense.\n\n\u003ccontinueRight/\u003e\n\n- After a blockquote or code fence region, include a `\u003ccontinueRight/\u003e` tag.\n- It will cause that blockquote/fence region to continue flowing into whatever\n  comes after it in the left column.\n- Until another blockquote or code fence region begins.\n\n#### Images In Right Column\n\nImages may also be placed into the right column of the document by placing\nthem in blockquotes.\n\n```markdown\n\u003e ![Another Beach](site/images/beach2.jpg)\n```\n\nLike all other elements, you may place a `\u003ccontinueRight/\u003e` after blockquote\ncontaining the image to get subsequent content to flow alongside the image on\nits left side:\n\n\u003e ![Another Beach](site/images/beach2.jpg)\n\n\u003ccontinueRight/\u003e\n\n\n\u003e - Such as this list here\n\u003e - **And this bold line here**\n\n#### Code Tabs\n\nYou can create [Docusaurus](https://docusaurus.io/docs/en/doc-markdown) style\ncode toggle switches for viewing multiple different code samples. In this\nexample, clicking on the headers (reason, javascript, ocaml) will toggle\nbetween different syntaxes for a particular print command.\n\n\u003c!--CODE_TABS--\u003e\n```reason\nConsole.log([\"This\", \"Logs\", \"Reason\", \"Lists\"]);\nLibrary.callSomeFunction(10, 200);\n```\n\n```javascript\nConsole.log([\"This\", \"Logs\", \"Reason\", \"Arrays\"]);\nlibrary.callSomeFunction(10, 200);\n```\n\n```ocaml\nConsole.log [\"This\", \"Logs\", \"Ocaml\", \"Lists\"]\nLibrary.callSomeFunction 10 200;\n```\n\u003c!--END_CODE_TABS--\u003e\n\n\n\nTo create code tabs, place multiple code blocks between special `CODE_TABS`\nHTML comments as follows.\n\n````md\n \u003c!--CODE_TABS--\u003e\n ... multiple code blocks go here...\n \u003c!--END_CODE_TABS--\u003e\n\n````\n\n#### Custom Tab Titles\n\nBy default, code tab titles are inferred from the code block syntaxes, but you\nmay give custom names to the tabs by including an HTML comment before each code\nexample.\n\n\n````md\n \u003c!--CODE_TABS--\u003e\n \u003c!--My JS Code Block--\u003e\n ...js code block...\n \u003c!--My Python Code Block--\u003e\n ...python code block...\n \u003c!--END_CODE_TABS--\u003e\n````\n\nNote: Specifying the title from this code block syntax is a Paradoc feature,\nnot supported in Docusaurus.\n\n\nThe previous example produces the following result:\n\n\u003c!--CODE_TABS--\u003e\n\n\u003c!--My JS Code Block--\u003e\n```js\nconsole.log('Hello, world!');\n```\n\u003c!--My Python Code Block--\u003e\n```py\nprint('Hello, world!')\n```\n\u003c!--END_CODE_TABS--\u003e\n\n\n### UI Enhancements\n\n#### Medium-Zoom Images\n\nImages are specified using standard markdown syntax, but they are enhanced with\na plugin called [Medium Zoom](https://medium-zoom.francoischalifour.com/).\n\n```markdown\n![Beach](site/logo.svg)\n```\n\n![Beach](site/images/beach.jpg)\n\n\u003e Click on the image to view a full view. Click, or scroll a small amount to\n\u003e cause the image to animate back into place.\n\n\u003ccontinueRight/\u003e\n\n\n\n#### Buttons\n\nInclude a `\u003e` at the end of your link text (for instance: `Continue \u003e`), to\nturn them into buttons. This is a feature from flatdoc.\n\n\u003e [Go To Github \u003e][github]\n\n\n### YAML Headers\n\nParadoc parses valid key/value items from \"YAML headers\". These headers are\nwhere you specify information that applies to that entire document.  YAML\nheaders consist of an unlimited number of `key:value` lines sandwiched between\ntwo `---` at the start of the document, immediately after the initial Paradoc\n`\u003cscript\u003e`.\n\nYou can specify any key/value pairs you like - but Paradoc will look for\ncertain keys to configure your website and rendering. See [Configuring\nPages](configuring-pages.html).\n\n\n```html\n\u003cscript src=\"site/Paradoc.js\"\u003e\u003c/script\u003e\n---\ntitle: me\ndescription: \"Hi there here is an escaped quote \\\" inside of quotes\"\nanythingYouWant: hey\n---\n```\n\n\n### Multi-Doc Pages\n\nTo add another doc page, have an existing page specify the new page as its\n`nextPage:` in the [Page Header](#page-headers) . Then make sure that new page\nactually exists, and has the Paradoc script include as usual.\n\n\u003e Note: All pages should also supply a `rootPage:` header property that\n\u003e specifies the \"first page\" in the list.\n\nThe following header specifies that the next markdown page should be\n`my-next-page.html`, and that the starting \"root page\" should be `README.html`.\n\n\n```html\n\u003cscript src=\"site/Paradoc.js\"\u003e\u003c/script\u003e\n---\ntitle: me\nnextPage: my-next-page\nrootPage: readme\n---\n```\n\n\u003ccontinueRight/\u003e\n\nSee how to [Add More Pages](configuring-pages.html#adding-pages)\n\n\n## Search Features\n\nParadoc supports _offline_ search across all of the documents that are\n[added](configuring-pages.html#adding-pages). No build steps or servers are\nrequired to search, and no subscriptions to search services are required.\nContent is searched interactively while authoring docs locally, when users\nconsume your deployed site, and when users save local copies of your deployed\nsite to disk.\n\n\n#### Offline Search\n- Press the \u003ckbd\u003e/\u003c/kbd\u003e key and start typing.\n- Searches across multiple pages.\n- No server, no build steps.\n\n\n#### Keyboard Interactions\n\n| Keyboard                                                             | Action                                       |\n|--------------------------------------------------------------------- |----------------------------------------------|\n| \u003ckbd\u003e/\u003c/kbd\u003e                                                         | Focus the Search input                       |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e                                                       | Close search results and blur search input   |\n| \u003ckbd\u003eCtrl+c\u003c/kbd\u003e or \u003ckbd\u003eCtrl+\\[\u003c/kbd\u003e                              | Toggle search results open when focused      |\n| \u003ckbd\u003eDown\u003c/kbd\u003e or \u003ckbd\u003eCtrl+n\u003c/kbd\u003e                                 | When results open, move up / down in results |\n| \u003ckbd\u003eUp\u003c/kbd\u003e or \u003ckbd\u003eCtrl+p\u003c/kbd\u003e                                   | When results open, move up / down in results |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e or Click                                            | Go to currently selected result              |\n\n\n## Change Resistant Deep Linking\n\nAll content in Paradoc pages can be \"deep linked\" to. This means that you can\ncreate a url link to a specific paragraph, code sample, or table row (not just\nthe headers).\n\nThese links are \"change resistant\", meaning that the content can be moved to another location\nin the document, and all the links that have proliferated on the internet will still work correctly.\n\nIt also means that the contents that are linked can be changed (fixing typos,\nrefactoring sentence structure), and all proliferated links to that specific\ncontent will still usually work (up to a certain amount of changes).\n\nThis works by creating a text fingerprint of the content and when loading the\npage, finding the content that most closely matches that fingerprint in the\nurl. Even if the text has changed changes Paradoc will find the best match\npossible.\n\n###### Try It Out\n\nHit \u003ckbd\u003e/\u003c/kbd\u003e to search for anything, and hit enter on a search result. Then\ncopy/paste the url into a new browser window. The search results encode the\nchange resistant deep link in the url, and you can share that specific search\nresult with anyone or link to it from a blog while feeling confident your links\nwon't break.\n\n\n## Deploying\n\n### Easy Optimizing With Chrome\n\nJust \"Save As\" in Chrome, select \"Complete Webpage\" to generated an optimized,\npre-rendered version of the site with all docs served as a single page application\nwith working online/offline search.\n\n### Packing Into A Single `.html` file.\n\"Save As\" in Chrome generates an optimized rendered build of your website as a\nsingle page application, but it will generate a folder with assets/styles and\nimages for your docs to be distributed/deployed along with your main html page.\nYou can take it even further also optimize your docs page into a single,\nminified `.html` file which bundles all of its resources *including* fonts and\nimages! There are many benefits to the way Paradoc compresses your docs site\ninto a single, shareable `.html` file.\n\n```\ncd site\nnpm install\nnode ./Paradoc.js ../readme.html\n```\n\nNow you can deploy `../readme.bookmark-inlined.html` as a single file to any\nweb host, and it will operate as a single page application.\n\nWith this mode:\n- Paradoc prerenders at build time instead of page load time (faster loading).\n- The document is served as a single web request.\n- Easily send the docs as an attachment in Discord/Messenger chat thread.\n- Save your online docs using the browser's '\"Save As\"\n- Paradoc makes sure your page looks exactly the same on anyone's computer,\n  including the fonts.\n\n\n## More\n\n#### Issues:\nYou must only load markdown html files that you authored and trust. Currently,\nthe way that the `marked` library is being used does not sanitize the output\nbefore injecting it into the DOM.\n\n\n### Acknowledgements\nSee [ORIGINS.md](./ORIGINS.md) for links and licenses of various\ncomponents that are embedded in this project.\n\n\n\n[github]: https://github.com\n[fences]:https://help.github.com/articles/github-flavored-markdown#syntax-highlighting\n[hljs]: https://highlightjs.org/\n[stylus]: https://stylus-lang.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordwalke%2Fparadoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjordwalke%2Fparadoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordwalke%2Fparadoc/lists"}