jupyterlab / theme-cookiecutter

A cookiecutter template to help you make new JupyterLab theme extensions

theme-cookiecutter

Archived

This project is archived. It is now possible to create a Theme Extension for JupyterLab using the following cookiecutter: https://github.com/jupyterlab/extension-cookiecutter-ts.

A cookiecutter template to help you make new JupyterLab theme extensions.

Examples

Usage

Install cookiecutter:

pip install cookiecutter

Use cookiecutter to generate a package:

cookiecutter https://github.com/jupyterlab/theme-cookiecutter

Prompts

The cookiecutter will prompt you with the following questions and generate a project according to your responses:

• author_name: Your full name.
• python_name: The name of the Python package for your JupyterLab extension (e.g. jupyterlab_pink_theme).
• labextension_name: Your JupyterLab extension name (e.g. @my-organization/jupyterlab-pink-theme).
• project_short_description: A short description of your JupyterLab theme extension.
• has_binder: Whether you extension has a binder link or not.
• repository: Your theme's repository. If the code of your theme is hosted on Github, this should just be the main Github url (e.g. https://github.com/my-organization/jupyterlab_pink_theme).

Project structure

Once you fill in the cookiecutter prompts, you'll get a basic theme extension. The files within are structured as follows:

• python_name
  • style: The assets (.css files, images, etc) that will make up your theme's actual style. This start out with the style from the default Jupyterlab light theme.
  • src - The extension source.
    • index.ts: Entry point for the JupyterLab extension
  • package.json: Metadata files that defines the files in your extension and their dependencies
  • tsconfig.json: Tells the TypeScript compiler how to build your extension
  • setup.py: The Python distribution file

Package names

We suggest that extension names start with jupyterlab_ and use underscores or dashes if needed to improve readability, such as jupyterlab_myextension.

theme-cookiecutter's Issues

Trying to import fonts from css causes extension installation to break

If you try to import a font, say with

 @font-face {
    font-family: 'Whatever';
    src: url('fonts/Whatever.ttf') format('truetype');
    font-weight: 400;
    font-style: normal;
}

Then building jupyterlab with the extension will fail with error:

Module build failed (from ./node_modules/mini-css-extract-plugin/dist/loader.js):
Error: Automatic publicPath is not supported in this browser

Clarify documentiation for what color flags do

Problem

I'm trying to build a theme, and it's hard to figure out what some of the css variables do. Example:

  --jp-mirror-editor-variable-color: var(--foreground-light);
  --jp-mirror-editor-variable-2-color: var(--magenta);
  --jp-mirror-editor-variable-3-color: var(--gray);

In this example, --jp-mirror-editor-variable-color appears to change all variables, while variable-2-color and variable-3-color don't do anything.

Proposed Solution

Additional documentation (inline with the template or in the readme / wiki) would be super helpful!

Loading SVG files fails

I think the cookiecutter version only serves files in the root, while icons, etc are deeper down, also
perhaps missing some types (svg, png, etc)
From package.json:

cookiecutter version:
    "style/*.css",
    "style/*.ttf",
    "style/*.eot",
    "style/*.woff",
    "style/*.woff2"

theme-light-extension version:
    "style/**/*.{css,eot,gif,html,jpg,json,png,svg,woff2,ttf}"

To archive

Follow-up Pr

To reduce maintenance burden this merge https://github.com/jupyterlab/theme-cookiecutter

+1, since the theme cookiecutter can easily get out of sync and doesn't necessarily benefit from the improvements made to the ts cookiecutter here (for example CI and releaser config).

Some follow-up steps that come to mind:

• Archive: https://github.com/jupyterlab/theme-cookiecutter
• Update the extension tutorial
• Update the apod repo

Originally posted by @jtpio in jupyterlab/extension-cookiecutter-ts#196 (comment)

"style/*.foo" globs in package.json too specific

First I'd like to say thank you for putting this together. I'd been searching for a while now for a way to make my custom theme work. From what I've seen, this is necessary for the icons to work with a custom theme. The install, and subsequent rebuild doesn't seem to copy over the svg files so the console is littered with 404's but having it run through webpack obviously doesn't have this issue.

Originally posted by @mountain01 in #1 (comment)

The issue that @mountain01 pointed out is actually separate from the webpack discussion. The file specifiers in the package.json template are too specific, and so miss certain files.

Changing the favicon using this extension

(See my post here on the Jupyter forums)

New to notebook extensions and most all web development concepts. I’m attempting to change JupyterLab’s favicon using this cookiecutter theme, with the ultimate goal of being able to change the favicon based on a config file. I’m using a slight modification of this SOF post, included within my src/index.ts file.

let head = document.head || document.getElementsByTagName('head')[0];

function changeFavicon(src: string) {
  let link = document.createElement('link'),
       oldLink = document.getElementById('dynamic-favicon');
  link.id = 'dynamic-favicon';
  link.rel = 'icon';
  link.type = 'image/x-icon';
  link.href = src;
  if (oldLink) {
    head.removeChild(oldLink);
  }
  head.appendChild(link);
}

When I call…

changeFavicon('http://www.google.com/favicon.ico');

…the favicon changes appropriately. But how would I access a favicon.ico file stored within my very own local extension directory?

A step further, how could I change the path to different favicon files using a config file?

Invalid name of org_name

Hi!

I input text "microcoder" in a field org_name, after that begin install the package and I got an error:

jupyter labextension install .

An error occured.
ValueError: "/home/alpine/juptheme/jupyterlab-ubu-theme" is not a valid npm package
See the log file for details:  /tmp/jupyterlab-debug-4e18d3kv.log

/tmp/jupyterlab-debug-4e18d3kv.log:

Node v12.15.0

Yarn configuration loaded.
> node /usr/lib/python3.8/site-packages/jupyterlab/staging/yarn.js install
yarn install v1.21.1
error package.json: Name contains illegal characters
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

> /usr/bin/npm pack /home/alpine/juptheme/jupyterlab-ubu-theme
npm ERR! Invalid name: "microcoder/jupyterlab-ubu-theme"

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/alpine/.npm/_logs/2020-04-03T06_20_28_921Z-debug.log

Traceback (most recent call last):

  File "/usr/lib/python3.8/site-packages/jupyterlab/debuglog.py", line 47, in debug_logging
    yield

  File "/usr/lib/python3.8/site-packages/jupyterlab/labextensions.py", line 93, in start
    ans = self.run_task()

  File "/usr/lib/python3.8/site-packages/jupyterlab/labextensions.py", line 138, in run_task
    return any([

  File "/usr/lib/python3.8/site-packages/jupyterlab/labextensions.py", line 139, in <listcomp>
    install_extension(

  File "/usr/lib/python3.8/site-packages/jupyterlab/commands.py", line 388, in install_extension
    return handler.install_extension(extension, pin=pin)

  File "/usr/lib/python3.8/site-packages/jupyterlab/commands.py", line 603, in install_extension
    info = self._install_extension(extension, tempdir, pin=pin)

  File "/usr/lib/python3.8/site-packages/jupyterlab/commands.py", line 1499, in _install_extension
    info = self._extract_package(extension, tempdir, pin=pin)

  File "/usr/lib/python3.8/site-packages/jupyterlab/commands.py", line 1578, in _extract_package
    raise ValueError(msg % source)

ValueError: "/home/alpine/juptheme/jupyterlab-ubu-theme" is not a valid npm package

Exiting application: jupyter