{"id":13507033,"url":"https://github.com/danielfrg/pelican-jupyter","last_synced_at":"2025-03-30T07:31:53.708Z","repository":{"id":7318210,"uuid":"8636714","full_name":"danielfrg/pelican-jupyter","owner":"danielfrg","description":"Pelican plugin for blogging with Jupyter/IPython Notebooks","archived":true,"fork":false,"pushed_at":"2023-04-06T22:47:33.000Z","size":414,"stargazers_count":423,"open_issues_count":22,"forks_count":105,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-05-21T08:09:40.480Z","etag":null,"topics":["blog","jupyter-notebook","pelican"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielfrg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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,"publiccode":null,"codemeta":null}},"created_at":"2013-03-07T21:16:48.000Z","updated_at":"2024-06-19T00:15:24.915Z","dependencies_parsed_at":"2024-06-19T00:15:22.951Z","dependency_job_id":"ae24d2b4-cd8b-4249-9b78-d2b012aa2f6c","html_url":"https://github.com/danielfrg/pelican-jupyter","commit_stats":{"total_commits":139,"total_committers":37,"mean_commits":"3.7567567567567566","dds":0.6115107913669064,"last_synced_commit":"49c1d3bf7efbc2f6f804441cc7839f62dcc74fb0"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfrg%2Fpelican-jupyter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfrg%2Fpelican-jupyter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfrg%2Fpelican-jupyter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfrg%2Fpelican-jupyter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielfrg","download_url":"https://codeload.github.com/danielfrg/pelican-jupyter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":207925727,"owners_count":14792328,"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":["blog","jupyter-notebook","pelican"],"created_at":"2024-08-01T02:00:20.104Z","updated_at":"2024-08-01T02:00:48.595Z","avatar_url":"https://github.com/danielfrg.png","language":"Jupyter Notebook","funding_links":[],"categories":["Plugins","Jupyter Notebook"],"sub_categories":[],"readme":"# NOT MAINTAINED\n\n- I have not used this project myself on a long time\n- No issues or PRs can be created\n- I have moved on to [mkdocs](https://www.mkdocs.org/) and my [mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter) plugin and I recommend to do the same\n\n# pelican-jupyter: Pelican plugin for Jupyter Notebooks\n\n[![pypi](https://badge.fury.io/py/pelican-jupyter.svg)](https://pypi.org/project/pelican-jupyter/)\n[![build](https://github.com/danielfrg/pelican-jupyter/workflows/test/badge.svg)](https://github.com/danielfrg/pelican-jupyter/actions/workflows/test.yml)\n[![coverage](https://codecov.io/gh/danielfrg/pelican-jupyter/branch/master/graph/badge.svg)](https://codecov.io/gh/danielfrg/pelican-jupyter?branch=master)\n[![license](https://img.shields.io/:license-Apache%202-blue.svg)](https://github.com/danielfrg/pelican-jupyter/blob/master/LICENSE.txt)\n\n## Installation\n\n```\npip install pelican-jupyter\n```\n\n### Pelican and Jupyter versions\n\nThe main focus is to run with the latest versions of the packages but there is a good chance the plugin will work correctly with older versions of Pelican and Jupyter/.\nThe recommended version of libraries are:\n\n- `pelican\u003e=4`\n- `notebook\u003e=6`\n- `nbconvert\u003e=5`\n\n## Usage\n\nThis plugin provides two modes to use Jupyter notebooks in [Pelican](https://getpelican.com):\n\n1. As a new markup language so `.ipynb` files are recognized as a valid filetype for an article\n2. As a liquid tag based on the [liquid tags plugin](https://github.com/getpelican/pelican-plugins/tree/master/liquid_tags) so notebooks can be\nincluded in a regular post using Markdown (`.md`) files.\n\n### Mode A: Markup Mode\n\nOn your `pelicanconf.py`:\n\n```python\nMARKUP = (\"md\", \"ipynb\")\n\nfrom pelican_jupyter import markup as nb_markup\nPLUGINS = [nb_markup]\n\nIGNORE_FILES = [\".ipynb_checkpoints\"]\n```\n\nWith this mode you need to pass the MD metadata to the plugins with one of this two options:\n\n#### Option 1: `.nbdata` metadata file\n\nPlace the `.ipynb` file in the content folder and create a new file with the\nsame name as the ipython notebook with extension `.nbdata`.\nFor example if you have `my_post.ipynb` create `my_post.nbdata`.\n\nThe `.nbdata` should contain the metadata like a regular Markdown based article (note the empty line at the end, you need it):\n\n```\nTitle:\nSlug:\nDate:\nCategory:\nTags:\nAuthor:\nSummary:\n\n```\n\nYou can specify to only include a subset of notebook cells with the\n`Subcells` metadata item.\nIt should contain the index (starting at 0) of first and last cell to include\n(use `None` for open range).\nFor example, to skip the first two cells:\n\n```\nSubcells: [2, None]\n```\n\n### Option 2: Metadata cell in notebook\n\nWith this option, the metadata is extracted from the first cell of\nthe notebook (which should be a Markdown cell), this cell is then ignored when the notebook is rendered.\n\nOn your `pelicanconf.py`:\n\n```python\nMARKUP = (\"md\", \"ipynb\")\n\nfrom pelican_jupyter import markup as nb_markup\nPLUGINS = [nb_markup]\nIPYNB_MARKUP_USE_FIRST_CELL = True\n\nIGNORE_FILES = [\".ipynb_checkpoints\"]\n```\n\nNow, you can put the metadata in the first notebook cell in Markdown mode, like this:\n\n```markdown\n- title: My notebook\n- author: John Doe\n- date: 2018-05-11\n- category: python\n- tags: pip\n```\n\n## Mode B: Liquid tags\n\nOn your `pelicanconf.py`:\n\n```python\nMARKUP = ('md', )\n\nfrom pelican_jupyter import liquid as nb_liquid\nPLUGINS = [nb_liquid]\n\nIGNORE_FILES = [\".ipynb_checkpoints\"]\n```\n\nAfter this you can use a liquid tag to include a notebook in any regular markdown article,\nfor example `mypost.md`:\n\n```\nTitle:\nSlug:\nDate:\nCategory:\nTags:\nAuthor:\nSummary:\n\n{% notebook path/from/content/dir/to/notebook.ipynb %}\n```\n\n## Recommend mode?\n\nPersonally I like Method A - Option 1 since I write the Notebooks first and then I just add\nthe metadata file and keeps the notebook clean.\n\nThe Liquid tag mode provide more flexibility to combine an existing notebook code or output with extra text on a Markdown.\nYou can also combine 2 or more notebooks in this mode.\nThe only problem with the liquid tag mode is that it doesn't generate a summary for the article\nautomatically from the notebook so you have to write it in the source `.md` file that includes the notebook.s\n\nYou can use both modes at the same time but you are probably going to see a exception that\nprevents conflicts, ignore it.\n\n## Note on CSS\n\nIf the notebooks look bad on your pelican theme this can help.\n\nThere is some issues/conflicts regarding the CSS that the Jupyter Notebook requires and the pelican themes.\n\nI do my best to make the plugin work with every theme but for obvious reasons I cannot guarantee that it will look good in any pelican theme.\n\nJupyter Notebook is based on bootstrap so you probably will need your theme to be based on that it if you want the html and css to render nicely.\n\nI try to inject only the necessary CSS by removing Jupyter's bootstrap code and only injecting the extra CSS code.\nIn some cases but fixes are needed, I recommend looking at how [my theme](https://github.com/danielfrg/danielfrg.com) fixes them.\n\nYou can suppress the inclusion of any Notebook CSS entirely by setting `IPYNB_SKIP_CSS=True`, this allows more flexibility on the pelican theme.\n\nThe `IPYNB_EXPORT_TEMPLATE` option is another great way of extending the output natively using Jupyter nbconvert.\n\n## Settings\n\n**Note:** If you are using the Liquid mode you need to set the variables like this inside the `pelicanconf.py`.\n\n```\nLIQUID_CONFIGS = ((\"IPYNB_EXPORT_TEMPLATE\", \"notebook.tpl\", \"\"), )\n```\n\nIf you are using the Markup mode then just add this variables to your `pelicanconf.py`.\n\n| Setting | Description |\n|---|---|\n| `IPYNB_FIX_CSS = True` | [markup and liquid] Do not apply any of the plugins \"fixes\" to the Jupyter CSS use all the default Jupyter CSS. |\n| `IPYNB_SKIP_CSS = False` | [markup and liquid] Do not include (at all) the notebook CSS in the generated output. This is usefull if you want to include it yourself in the theme. |\n| `IPYNB_PREPROCESSORS` | [markup and liquid] A list of nbconvert preprocessors to be used when generating the HTML output. |\n| `IPYNB_EXPORT_TEMPLATE` | [markup and liquid] Path to nbconvert export template (relative to project root). For example: Create a custom template that extends from the `basic` template and adds some custom CSS and JavaScript, more info here [docs](http://nbconvert.readthedocs.io/en/latest/customizing.html) and [example here](https://github.com/jupyter/nbconvert/blob/master/nbconvert/templates/html/basic.tpl). |\n| `IPYNB_STOP_SUMMARY_TAGS = [('div', ('class', 'input')), ('div', ('class', 'output')), ('h2', ('id', 'Header-2'))]` | [markup only] List of tuples with the html tag and attribute (python HTMLParser format) that are used to stop the summary creation, this is useful to generate valid/shorter summaries. |\n| `IPYNB_GENERATE_SUMMARY = True` | [markup only] Create a summary based on the notebook content. Every notebook can still use the s`Summary` from the metadata to overwrite this. |\n| `IPYNB_EXTEND_STOP_SUMMARY_TAGS` | [markup only] List of tuples to extend the default `IPYNB_STOP_SUMMARY_TAGS`. |\n| `IPYNB_NB_SAVE_AS` | [markup only] If you want to make the original notebook available set this variable in a  is similar way to the default pelican `ARTICLE_SAVE_AS` setting. This will also add a metadata field `nb_path` which can be used in the theme. e.g. `blog/{date:%Y}/{date:%m}/{date:%d}/{slug}/notebook.ipynb` |\n| `IPYNB_COLORSCHEME` | [markup only] Change the pygments colorscheme used for syntax highlighting |\n| `IGNORE_FILES = ['.ipynb_checkpoints']` | [Pelican setting useful for markup] Prevents pelican from trying to parse notebook checkpoint files. |\n\nExample template for `IPYNB_EXPORT_TEMPLATE`:\n\n```\n{%- extends 'basic.tpl' -%}\n\n{% block header %}\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.min.js\"\u003e\u003c/script\u003e\n\n\u003cstyle type=\"text/css\"\u003e\ndiv.code_cell {\n    border: 2px solid red;\n}\n\u003c/style\u003e\n{%- endblock header %}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfrg%2Fpelican-jupyter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielfrg%2Fpelican-jupyter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfrg%2Fpelican-jupyter/lists"}