{"id":13696200,"url":"https://github.com/pelican-plugins/show-source","last_synced_at":"2025-04-10T04:32:47.688Z","repository":{"id":52032134,"uuid":"333072892","full_name":"pelican-plugins/show-source","owner":"pelican-plugins","description":"Link to the source text of your posts","archived":false,"fork":false,"pushed_at":"2024-07-02T01:08:29.000Z","size":39,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T16:23:33.457Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pelican-plugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"custom":"https://donate.getpelican.com","liberapay":"pelican"}},"created_at":"2021-01-26T12:08:08.000Z","updated_at":"2024-11-10T16:42:56.000Z","dependencies_parsed_at":"2024-04-13T00:42:18.178Z","dependency_job_id":"f8b94f01-fc81-429b-b479-65d1d5942789","html_url":"https://github.com/pelican-plugins/show-source","commit_stats":{"total_commits":18,"total_committers":5,"mean_commits":3.6,"dds":"0.33333333333333337","last_synced_commit":"29a61114da668c5be578775396487e44a002eae1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pelican-plugins%2Fshow-source","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pelican-plugins%2Fshow-source/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pelican-plugins%2Fshow-source/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pelican-plugins%2Fshow-source/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pelican-plugins","download_url":"https://codeload.github.com/pelican-plugins/show-source/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248157655,"owners_count":21057048,"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","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-08-02T18:00:37.242Z","updated_at":"2025-04-10T04:32:47.411Z","avatar_url":"https://github.com/pelican-plugins.png","language":"Python","readme":"Show Source: A Plugin for Pelican\n=================================\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/pelican-plugins/show-source/main.yml?branch=main)](https://github.com/pelican-plugins/show-source/actions)\n[![PyPI Version](https://img.shields.io/pypi/v/pelican-show-source)](https://pypi.org/project/pelican-show-source/)\n![License](https://img.shields.io/pypi/l/pelican-show-source?color=blue)\n\nThis Pelican plugin allows you to place a link to your posts’ source content files in the same way that [Sphinx][] does. It works for both pages and articles.\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n    python -m pip install pelican-show-source\n\nFor more detailed plugin installation instructions, please refer to the [Pelican Plugin Documentation][].\n\nConfiguration\n-------------\n\nTo enable the plugin, ensure that you have `SHOW_SOURCE_ON_SIDEBAR = True` or `SHOW_SOURCE_IN_SECTION = True` in your settings file.\n\n`SHOW_SOURCE_ALL_POSTS = True` will show the source for all posts, instead of only posts with the source explicitly made available (see below.) By default, this is `False`.\n\nThe option `SHOW_SOURCE_PRESERVE_EXTENSION` (`False` by default) controls the extension of the output source file. If `True`, the file will have the same extension as the real source document (`.rst`, `.md`, etc). Otherwise, it will be a plain-text `.txt` file.\n\nMaking Source Available for Posts\n---------------------------------\n\nIn order to mark posts so that their source may be seen, use the following metadata fields (unless overridden) for reStructuredText documents:\n\n```rst\n:show_source: True\n```\n\nAlternatively, for Markdown syntax:\n\n```markdown\nShow_source: True\n```\n\nThe plugin will render your source document URL to a corresponding `article.show_source_url` (or `page.show_source_url`) attribute, which is then accessible in the site templates.\n\nShow Source in the Templates\n----------------------------\n\nTo get the “show source” links to display in the article or page you will have to modify your theme, either as a sidebar display or at the foot of an article.\n\n### Article or Page Sidebar Display\n\nHow to get the source link to appear in the sidebar using the [pelican-bootstrap3][] theme:\n\n```html\n{% if SHOW_SOURCE_ON_SIDEBAR %}\n    {% if (article and article.show_source_url) or (page and page.show_source_url) %}\n        \u003cli class=\"list-group-item\"\u003e\u003ch4\u003e\u003ci class=\"fa fa-tags fa-file-text\"\u003e\u003c/i\u003e\u003cspan class=\"icon-label\"\u003eThis Page\u003c/span\u003e\u003c/h4\u003e\n            \u003cul class=\"list-group\"\u003e\n                \u003cli class=\"list-group-item\"\u003e\n                    {% if article %}\n                    \u003ca href=\"{{ SITEURL }}/{{ article.show_source_url }}\"\u003eShow source\u003c/a\u003e\n                    {% elif page %}\n                    \u003ca href=\"{{ SITEURL }}/{{ page.show_source_url }}\"\u003eShow source\u003c/a\u003e\n                    {% endif %}\n                \u003c/li\u003e\n            \u003c/ul\u003e\n        \u003c/li\u003e\n    {% endif %}\n{% endif %}\n```\n\n### Article Footer Display\n\nFollowing is some code (yes, [pelican-bootstrap3][] again) to enable a source link at the bottom of an article:\n\n```html\n{% if SHOW_SOURCE_IN_SECTION %}\n    {% if article and article.show_source_url %}\n    \u003csection class=\"well\" id=\"show-source\"\u003e\n        \u003ch4\u003eThis Page\u003c/h4\u003e\n        \u003cul\u003e\n            \u003ca href=\"{{ SITEURL }}/{{ article.show_source_url }}\"\u003eShow source\u003c/a\u003e\n        \u003c/ul\u003e\n    \u003c/section\u003e\n    {% endif %}\n{% endif %}\n```\n\nOverriding Default Plugin Behaviour\n-----------------------------------\n\nThe default behaviour of the plugin is that revealing source is enabled on a case-by-case basis. This can be changed by the use of `SHOW_SOURCE_ALL_POSTS = True` in the settings file. This does mean that the plugin will publish all source documents no matter whether `show_source` is set in the metadata or not.\n\nUnless overridden, each document is saved as the article or page slug attribute with a `.txt` extension.\n\nSo for example, if your configuration had `ARTICLE_SAVE_AS` configured like so:\n\n```python\nARTICLE_SAVE_AS = \"posts/{date:%Y}/{date:%m}/{slug}/index.html\"\n```\n\n… your static HTML post and source text document will be like the following:\n\n```text\nposts/2016/10/welcome-to-my article/index.html\nposts/2016/10/welcome-to-my article/welcome-to-my article.txt\n```\n\nYou can add the `SHOW_SOURCE_FILENAME` variable in your settings file to override the source file name, so you could set the following:\n\n```python\nSHOW_SOURCE_FILENAME = \"my_source_file.txt\"\n```\n\nSo with the `ARTICLE_SAVE_AS` configured as above, the files would be saved\nthus:\n\n```text\nposts/2016/10/welcome-to-my article/index.html\nposts/2016/10/welcome-to-my article/my_source_file.txt\n```\n\nThis is the same behaviour for pages as well.\n\nContributing\n------------\n\nContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[existing issues]: https://github.com/pelican-plugins/show-source/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nLicense\n-------\n\nThis project is licensed under the AGPL-3.0 license.\n\n\n[Pelican Plugin Documentation]: https://docs.getpelican.com/en/latest/plugins.html\n[Sphinx]: https://www.sphinx-doc.org/\n[pelican-bootstrap3]: https://github.com/getpelican/pelican-themes/tree/master/pelican-bootstrap3\n","funding_links":["https://donate.getpelican.com","https://liberapay.com/pelican"],"categories":["Plugins"],"sub_categories":["Migrated to new architecture"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpelican-plugins%2Fshow-source","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpelican-plugins%2Fshow-source","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpelican-plugins%2Fshow-source/lists"}