Package: seafoam
Seafoamis a theme forPelican,
a static site generator written in Python.Theseafoamtheme is based on Bootstrap 3, and was first used atMinchin.ca.InstallationThe easiest way to install theseafoamtheme is through the use
of pip. This will also install the required dependencies automatically.pipinstallseafoamAlternatively, you can force the installation oflxml, which is a HTML
parser that is often faster than the default, and will be used if installed:pipinstallseafoam[lxml]If you are using Pelican v4.5 or newer and only namespace plugins,seafoamis set up as a namespace plugin and will automatically activate and configure
itself.If you are using a version of Pelican older that v4.5 or non-namespace plugins,
you will need to addseafoamto your list of plugins:# pelicanconf.pyPLUGINS=["pelican.plugins.seafoam",# others, as desired...]# the rest of the your configuration file...You may also need to configure the theme through the use of additional settings
(see below).RequirementsSeafoamrequires Pelican, theimage_processplugin, thejinja filtersplugin,beautifulsoup4, andsemantic_version. If the
theme is installed from pip, these should be automatically installed. If
needed, they can be manually installed with pip:pipinstallpelicanpipinstallpelican-image-processpipinstallpelican-jinja-filterspipinstallbeautifulsoup4pipinstallsemantic_versionSupported PluginsSeafoam also works with several other plugins for Pelican, but none of those
listed in this section are required.microblogging–
adds the ability to have “microposts”, and tweaks the formatting of the theme
based on their (assumed) shorter length.readtime– provides
estimated reading time for articles. Available from PyPI aspelican-readtime.post-stats–
provides estimated reading time for articles ifreadtimeis not available.
Available in thePelican Plugins collection.neighbors– provides
post-article links to the next and previous article on your blog and the
next and previous article in that category. Available on PyPI aspelican-neighours.static-comments(or the
olderpelican_comment_system)
– add static comments to your blog. Available on PyPI asminchin.pelican.plugins.static-comments.Related Posts–
adds therelated_postsvariable to the article’s context.Tipue SearchAdditional ImagesArticle with header imageMain article bodyCommentsComment FormMain ArchivesYearly ArchivesMonthly Archives404 Error PageAdditional SettingsThese settings can be set in yourpelicanconf.pyfile (your Pelican settings
file) to alter the behavior of the theme.If a value is given below, this represents the effective default value. If no
value is given, the effective default value isNone.If you are using this theme on a sub-site (i.e a directory of the “main site”),
look atMENUITEMS_2,MENUITEMS_2_AT, andMENUITEMS_2_AT_LINKsettings.If you are using this theme on a subdomain, look at theSITE_ROOT_URLsetting.If you want to disableImage Processfor local development, seeSEAFOAM_DEV_MODE.Seafoam also auto-configures itself when possible.  If you need to manually
create the default configuration, you would need the following:# pelicanconf.pyfrompelican.pluginsimportseafoamTHEME=seafoam.get_path()BOOTSTRAP_THEME="seafoam"# if PLUGINS is not defined on Pelican 4.5+, these plugins will autoloadPLUGINS=["pelican.plugins.seafoam","pelican.plugins.jinja_filters","pelican.plugins.image_process",# others, as desired...]IMAGE_PROCESS={"article-feature":["scale_in 848 848 True"],"index-feature":["scale_in 263 263 True"],}# Generate 404 error pageTEMPLATE_PAGES={"404.html":"404.htm"',}# the rest of the your configuration file...This documentation has to be manually updated. If the settings no longer match
the theme’s behavior, or a setting is missing from here, please open a ticket
onGitHub.ABOUT_MEYou can show a short blurb of text about yourself and a picture. This setting
is the paragraph. Raw HTML is accepted. See theAVATARsetting to set the
picture.ADAMThese ADAM settings were originally set up to support my genealogy sub-site
(the original name of the the pre-processor I was using as called “Adam”). If
this is set toFalse, the rest of theADAM_*settings won’t be active.
These settings are probably generic enough that you could use these for any
generator or outside program used to help generate your site.ADAM_COPY_DATEOverride the copyright date in the footer. (Provide a string).ADAM_FOOTERAn extra “page footer” to apply to all pages. (Provide an HTML string.)ADAM_LINKLink target for the Adam version text.ADAM_UPDATEDOverride the updated date.ADAM_VERSIONReported name and version of “Adam”.ADDTHIS_PROFILEYou can enable sharing buttons throughAddThisby this setting to your AddThis profile-id. This will display a Tweet,
Facebook Like and Google +1 button under each post.ARCHIVES_URLSame as the regular Pelican setting.ASSET_CSSSet toTrueif you want theassetplugin to compile your CSS.ASSET_JSSet toTrueif you want theassetplugin to compile your Javascript.AUTHORWho to list as the copyright belonging to in the site footer.AUTHORS_URLSame as the regular Pelican setting.AVATARYou can show a short blurb of text about yourself and a picture. This setting
is the path to the picture. See theABOUT_MEsetting to set the
descriptive paragraph.BOOTSTRAP_NAVBAR_INVERSE = FalseApply inverse CSS setting to Navbar. Changing this will swap the top
navigation bar between light and dark.BOOTSTRAP_THEME = “seafoam”Use this to set the “colour scheme” of the framework. Valid values areseafoamandstrathcona.seafoamteal on darker green;strathconais maroon on white. This is a Automatically set toseafoamby the internal plugin if unspecified. Other values (including leaving this
unset) are not expected to work correctly.CATEGORIES_URLSame as the regular Pelican setting.CATEGORY_IMAGES = {}Provide a default featured image by category. If an image is set in the
article metadata, that will override this.Provide a dictionary where the key is the category name and the value is the
path of the image, relative to the SITEURL.CC_ATTR_MARKUPOptionally, you can include attribution markup in the CC license mark by
setting this toTrue.CC_LICENSESet a site-wide Creative Commons License by specify the “short name” of the
license (likeCC_BY, orCC-BY-NC-ND). Alternately, useCC_LICENSE_COMMERCIALandCC_LICENSE_DERIVATIVESto “build a
license”.CC_LICENSE_COMMERCIAL“yes” if commercial use is permitted, “no” otherwise. Use this in lieu ofCC_LICENSEand in combination withCC_LICENSE_DERIVATIVESto “build a
license”.CC_LICENSE_DERIVATIVES“yes” is derivatives are permitted, “no” otherwise. Use this in lieu ofCC_LICENSEand in combination withCC_LICENSE_COMMERCIALto “build a
license”.CUSTOM_CSSLink, relative to SITEURL, to a custom CSS file.CUSTOM_CSS_LIST = []Custom CSS to load; can be either absolute links, or relative links. If the
listed item starts with//,http://,https://, it is assumed to
be absolute link and added as-is to the markup. Otherwise, the link is
assumed to be relative to SITEURL.CUSTOM_JS_LIST = []Custom Javascript to load; can be either scripts, absolute links, or relative
links. If the listed item starts with<script, then the item is assumed
to be the contents of a script, including opening and closing tags, and so
added to the pages’ markup directly. If the listed item starts with//,http://,https://, it is assumed to be absolute link and added as-is
to the markup. Otherwise, the link is assumed to be relative to SITEURL.See alsoCUSTOM_JS_LIST_HEADandJQUERY_JS_IN_HEAD.CUSTOM_JS_LIST_HEAD = []Exactly the same format asCUSTOM_JS_LIST, but is added to the pages’<head>section rather than the end of the page. Generally, you will want
to put your Javascript at the end of the page (i.e. inCUSTOM_JS_LISTrather than here), as any Javascript referenced here must generally be
completely loaded before the page will start being rendered.WhenJQUERY_JS_IN_HEAD == True(not the default), JQuery is listed before
the other scripts listed here.See alsoCUSTOM_JS_LISTandJQUERY_JS_IN_HEAD.DEFAULT_LANG.DISPLAY_ARCHIVES_ON_MENU = TrueInclude archives on the main site menu.DISPLAY_BREADCRUMBS = FalseDisplay Breadcrumbs on site.See alsoMENUITEMS_2_ATandMENUITEMS_2_AT_LINKsettings.DISPLAY_CATEGORIES_ON_MENUInclude categories on the main site menu.DISPLAY_CATEGORIES_ON_SIDEBARInclude a listing of categories on the sidebar (assuming the sidebar is
active; seeHIDE_SIDEBARsetting)DISPLAY_PAGES_ON_MENUInclude a listing of pages on the sidebar (assuming the sidebar is active;
seeHIDE_SIDEBARsetting)DISPLAY_RECENT_POSTS_ON_SIDEBARInclude a listing of recent posts on the sidebar (assuming the sidebar is
active; seeHIDE_SIDEBARsetting). Also see theRECENT_POST_COUNTsetting.DISPLAY_TAGS_INLINE.DISPLAY_TAGS_ON_SIDEBAR = TrueInclude a listing of tags on the sidebar (assuming the sidebar is active;
seeHIDE_SIDEBARsetting)DISQUS_DISPLAY_COUNTSDisplay the number of comments (assuming Disqus comments are active; seeDISQUS_SITENAMEsettings)DISQUS_ID_PREFIX_SLUGSet this toTrueif you have configured your article URLs such that the
slug alone will likely not be unique. Ignored ifDISQUS_NO_IDisTrue.DISQUS_NO_IDThis theme sets identifiers for each article’s comment threads. If you are
switching from a theme that doesn’t (such as the Pelican built-in default)
this will result in existing comments getting lost. To prevent this, set
this setting toTrue.DISQUS_SITENAMESet to your Disqus sitename to activate Disqus comments on your site.You can also enable Disqus comments for pages. This is a per-page setting you
can control by adding a field comments to you pages’ metadata. Set it to
enabled to enable comments for that page. Comment-threads for pages will have
an id that is prefixed bypage-.You will probably only use this or the Pelican Comment System; odd results
may come if you try to use both together. See thePELICAN_COMMENT_SYSTEMsetting.DOCUTIL_CSSIf you’re using reStructuredText for writing articles and pages, you can
include the extra CSS styles that are used by the docutils-generated HTML by
setting this toTrue. This can be done as a global setting or setting it
in the metadata of a specific article or page.FAVICONThe location of your site’s FavIcon, relative to the SITEURL.FEED_ALL_ATOMSame as the regular Pelican setting. If set, a link to your Atom feed will
appear in the site’s HTML header and as a link in the footer of the site.FEED_ALL_RSSSame as the regular Pelican setting. If set, a link to your RSS feed will
appear in the site’s HTML header.GITHUB_REPO_COUNT = 5SeeGITHUB_USERsetting.GITHUB_SHOW_USER_LINKSeeGITHUB_USERsetting.GITHUB_SKIP_FORK = FalseSeeGITHUB_USERsetting.GITHUB_USERThe theme can show your most recently active GitHub repos in the sidebar. To
enable, set this to you GitHub username. Appearance and behavior can be
controlled using theGITHUB_REPO_COUNT,GITHUB_SKIP_FORK, andGITHUB_SHOW_USER_LINKvariables.GOOGLE_ANALYTICSUsed to activate “classic” Google Analytics. Set this to your account’s Google
Analytics ID. Although this setting doesn’t conflict withGOOGLE_ANALYTICS_UNIVERSAL, you will in most cases only use one or the
other. This has been deprecated by Google; seeGOOGLE_ANALYTICS_V4.GOOGLE_ANALYTICS_UNIVERSALUsed to activate “universal” Google Analytics (this is the new version). Set
this to your account’s ID (a number). Also setGOOGLE_ANALYTICS_UNIVERSAL_PROPERTY. Although this setting doesn’t
conflict withGOOGLE_ANALYTICS, you will in most cases only use one or
the other. This has been deprecated by Google (in June 2023); seeGOOGLE_ANALYTICS_V4.GOOGLE_ANALYTICS_UNIVERSAL_PROPERTYSet this to the Google Analytics “property” this site represents. See also
(and set)GOOGLE_ANALYTICS_UNIVERSAL.GOOGLE_ANALYTICS_V4Set this to activate Google Analytics v4.HIDE_SIDEBAR = FalseHides the sidebar, and all it’s contents. Also review the settingsDISPLAY_CATEGORIES_ON_SIDEBAR,DISPLAY_RECENT_POSTS_ON_SIDEBAR,DISPLAY_TAGS_ON_SIDEBAR,GITHUB_USER,LINKS, andTWITTER_USERNAME.HIDE_SITENAME = FalseHides the sitename in the site navbar.IMAGE_PROCESS = {“article-feature”: [“scale_in 848 848 True”], “index-feature”: [“scale_in 263 263 True”],}Used by theimage processplugin. The “article-feature” and “index-feature”
configurations are set by the included plugin if not set in your
configuration to something else.INDEX_COPY_DATECopyright date to display on the index page (homepage) of the site.JQUERY_JS_IN_HEAD = FalseBootstrap depends on JQuery. Typically, good practice is to load all your
Javascript from the end of your page. However, in certain cases, I’ve needed
to load JQuery sooner. So this moves loading JQuery from the end of the page
to the header. When active, JQuery is listed before the other scripts inCUSTOM_JS_LIST_HEAD. See alsoCUSTOM_JS_LIST_HEAD.LINKS = []Extra links to display sidebar. Provide a list of tuples of the form('name', 'link').MENUITEMSExtra items to add to the menu. Provide a list of tuples of the form(title, link, icon).linkis absolute, so build them using SITEURL,
if needed.iconhere is of the form of the CSS classes to be used; e.g.'fafa-fwfa-pencil'.iconcan be set toNone.If this is set, the working assumption is that the site you are generating is
a “sub-site”.MENUITEMS_2Extra items you want added as a sub-menu. Use in conjunction with theMENUITEMS_2_ATsetting. Provide a list of tuples of the form(title, link, icon).linkis absolute, so build them using SITEURL,
if needed.iconhere is of the form of the CSS classes to be used; e.g.'fafa-fwfa-pencil'.iconcan be set toNone.This setting is working on the assumption that your generated site in going
into a subdirectory of your “main” site.MENUITEMS_2_ATIfMENUITEMS_2is set, under which (main) menu item are these to be
displayed. This should match a “name” of one of the items onMENUITEMS;
if no match is found, these sub-menu items will not be displayed.When set and Breadcrumbs are enabled, all items on the site are shown to be
under both “home” (linked to at theSITE_ROOT_URL) andMENUITEMS_2_AT(linked to atMENUITEMS_2_AT_LINK).MENUITEMS_2_AT_LINKWhen set and Breadcrumbs are enabled, all items on the site are shown to be
under both “home” (linked to at theSITE_ROOT_URL) andMENUITEMS_2_AT(linked to atMENUITEMS_2_AT_LINK).MICROBLOG_DEV_URLThe project url for the microblogging plugin. Provided by the plugin, when in
use.MICROBLOG_VERSIONThe version of the microblogging plugin. Provided by the plugin, when in use.NAVBAR_ON_TOP = FalseIf True, the navigation menu is on top. If False, the navigation menu is
vertical on the left side of the page. Default is False.NEIGHBORSActivates the links to the next and previous articles, both in the “all
posts” index and the category-specific index. Requires theneighborsto be both
installed and activated (i.e. listed underPLUGINS).OPEN_GRAPH_FB_APP_IDYou can use this setting to provide a Facebookapp id. See theUSE_OPEN_GRAPHsetting.OPEN_GRAPH_IMAGEA default image to use with Open Graph. This is a filepath relative to your
SITEURL. See theUSE_OPEN_GRAPHsetting.PAGINATOR_LIMIT = 8Number of page number links to appear of the main “index” page of your
blog. The default of 8 results in showing a link to page 1, links the
three previous pages (8 divided by 2 and rounded down), a number
representing the current page, links to the next three pages, and a link
to the last page.PDF_PROCESSOR.PELICAN_COMMENT_SYSTEM = FalseSet this toTrueto active thepelican_comment_system.The Pelican Comment System hasfurther settingsthat are not used directly by the theme.You will probably only use this or Disqus; odd results may come if you try to
use both together. See also theDISQUS_SITENAMEsetting.PELICAN_COMMENT_SYSTEM_DISPLAY_COUNTS = TrueWhether to display the number of commentsPELICAN_COMMENT_SYSTEM_EMAIL_DOMAINThe domain name of the email where you want the comments to be emailed to
(i.e. the part after the@sign). See thePELICAN_COMMENT_SYSTEM_EMAIL_USERandPELICAN_COMMENT_SYSTEMsettings.PELICAN_COMMENT_SYSTEM_EMAIL_USERThe username of the email where you want the comments to be emailed to (i.e.
the part before the@sign). See thePELICAN_COMMENT_SYSTEM_EMAIL_DOMAINandPELICAN_COMMENT_SYSTEMsetting.PELICAN_COMMENT_SYSTEM_FEED, PELICAN_COMMENT_SYSTEM_FEED_ALLUsed internally to generate links to the Comment RSS/Atoms feeds.PELICAN_COMMENT_SYSTEM_IDENTICON_SIZE = 72The size of the Identicons generated by the Pelican Comment System.PIWIK_SITE_IDUsed for Piwik site analytics.PIWIK_SSL_URL = PIWIK_URLUsed for Piwik site analytics.PIWIK_URLUsed for Piwik site analytics.PLUGINSSame as the regular Pelican setting. If you set this, be sure to include the
internal pluginpelican.plugins.seafoamto get the theme to
auto-configure itself.PRJCTSet toTRUEto activeprjctsupport. Recommended segment to include in yourpelicanconf.py:# pelicanconf.pyimportprjctPRJCT=TruePRJCT_TODO,PRJCT_DONE=prjct.todo_export.to_html_dicts()PRJCT_PROJECTS=prjct.multi_source.project_list()PRJCT_ACTIVE_PROJECTS=prjct.multi_source.active_project_list()PRJCT_SOMEDAY_PROJECTS=prjct.config.someday_projects()PRJCT_COMPLETED_PROJECTS=prjct.config.completed_projects()PRJCT_DESC=prjct.descriptions.to_html_dict(markdown_extension_config=MARKDOWN['extension_configs'])PRJCT_VERSION=prjct.__version__PRJCT_FOOTER_URL=prjct.__url__Also add prjct to our direct templates list.PRJCT_ACTIVE_PROJECTSA list ofactiveprojects. Used to sort projects on the main prjct page.
See thePRJCTsetting.PRJCT_COMPLETED_PROJECTSA list ofactiveprojects. Used to sort projects on the main prjct page.
See thePRJCTsetting.PRJCT_DESCA dictionary of descriptions for each project, where the key is the name of
the project, and will match thetagpage where the output appears. The
return value is assumed to be a valid HTML segment. See thePRJCTsetting.PRJCT_DONEA dictionary of done to-do items for each project, where the key is the name
of the project, and will match thetagpage where the output appears. The
return value is assumed to be a valid HTML segment. See thePRJCTsetting.PRJCT_FOOTER_URL = ‘https://github.com/MinchinWeb/prjct’prjctURL used for link displayed in footer. See thePRJCTsetting.PRJCT_SOMEDAY_PROJECTSA list ofactiveprojects. Used to sort projects on the main prjct page.
See thePRJCTsetting.PRJCT_TODOA dictionary of open to-do items for each project, where the key is the name
of the project, and will match thetagpage where the output appears. The
return value is assumed to be a valid HTML segment. See thePRJCTsetting.PRJCT_VERSION = ‘’prjctversion displayed in footer. See thePRJCTsetting.PYGMENTS_STYLE = ‘native’This setting is currently ignored, and my preferred Pygments style is
included directly into the Seafoam CSS.RECENT_POST_COUNT = 5Number of recent posts to display on the sidebar. See theDISPLAY_RECENT_POSTS_ON_SIDEBARsetting.RELATED_POSTS_TEXT = ‘Related Posts:’Header for related posts listing. Requires that theRelated Posts Pluginbe active.SEAFOAM_DEV_MODE = FalseEnable this to speed local development by (effectively) disabling theImage
Processplugin. If you disable this in yourpelicanconf.py, you’ll
likely want to activate it in yourpublishconf.pyfile.SEAFOAM_ENCODING = “uft-8”The encoding that Beautiful Soup uses when run by the internal plugin.SEAFOAM_PARSER = “html.parser”Will be set to “lxml” is it is installed (which is the case with the most
recent versions of the requiredimage-processplugin).This is the parser that Beautiful Soup uses when run by the internal plugin.SEAFOAM_URL = “http://blog.minchin.ca/label/seafoam/”The project url of the theme (automatically provided by the bundled plugin).SEAFOAM_VERSION = pelican.plugins.seafoam.__version__The version of the theme (automatically provided by the bundled plugin).SITELOGOLink to the site logo (displayed in the navbar). This is relative to the
SITEURL.SITELOGO_SIZEThe width of the site logo in the navbar. Can be set to any valid CSS value
(i.e. %, em, px, etc). I have had good luck setting this to100%.SITENAMEThe name of your site, displayed in the navbar.SITEURLSame as the Pelican setting. Set this to where this Pelican site is actually
hosted. Also see theSITE_ROOT_URLsetting.SITE_ROOT_URL = SITEURLUse this if you’re hosting a subsite of some sort. This is where the links in
logo in the navbar and the home icon in the breadcrumbs will point to. See
also theMENUITEMS_2_ATsetting.SOCIALA list of your social media sites to be listed in the sidebar. Should be a
list of tuples in the form (‘social network name’, ‘full link to profile’).
The theme will display the logo of the network. See theHIDE_SIDEBARsetting.TAGS_TEXT = “Tags”Text used as the header to “Tags” (articles can be filed under multiple tags,
but assumes to be under a single (or no) category. Assumed to be plural.TAGS_URLSame as the Pelican setting.TEMPLATE_PAGES = {“404.html”: “404.html”,}Same as the Pelican setting. Automatically set by the internal plugin to
enable a 404 error page on GitHub pages (and perhaps elsewhere).THEME = pelican.plugins.seafoam.get_path()Same as the Pelican setting. Automatically set by the internal plugin.THEME_STATIC_DIRSame as the Pelican setting.TWITTER_USERNAMEYou can optionally provide a this which will be used to set the Twitter
username for the site and for the content creator.TWITTER_WIDGET_IDThe theme can show your twitter timeline in the sidebar. To enable, provide aTWITTER_USERNAMEand aTWITTER_WIDGET_ID.To get aTWITTER_WIDGET_ID, go to:https://twitter.com/settings/widgetsand selectCreate new. You’ll find theTWITTER_WIDGET_IDunder the html
or in the site url:https://twitter.com/settings/widgets/TWITTER_WIDGET_ID/editTYPOGRIFYWhether to activate Typography. Tyopgraphy is a library that automatically
adds a number of typographical flourishes. The necessary CSS is automatically
included in theseafoamCSS.The Typography Python library will needs to be installed, which is
installable via pip:pip install typogrifyNote that with Pelican 3.6, activating both the Pelican Comment System and
Typography at the same time cause issues. This issue was fixed in Pelican
3.7.USE_OPEN_GRAPH = TrueIn order to make the Facebook “like” button and other social sharing options
work better, the template contains Open Graph metatags like<metaproperty="og:type"content="article"/>. You can disable them by
setting this toFalse.See alsoOPEN_GRAPH_FB_APP_ID, andOPEN_GRAPH_FB_APP_IDsettings.It may also be helpful to review thesettings for Pelican itself.On articles, the theme also looks for theimagemetadata setting to provide
the “featured image* for the article.Known Issuesactivating both Typogrify and the Pelican Comment System on Pelican 3.6
causes issues. This issue has been fixed in Pelican 3.7.CreditsOriginal theme developed byDaan Debie.The idea that a theme could be installed as a Python package byJeff
Forcier’sAlabaster themefor Sphinx.