broeker / spacebook

💥 Create fast and simple documentation to explain almost anything. Uses Eleventy, Tailwind 2.0, and Alpine JS with an optional Netlify CMS.

Spacebook

Create your own spacebook and customize it to your needs. Spacebooks are speedy to set up, free, and 100% open source. Spacebooks are modern notebooks you can use to create documentation, sketch out new ideas, build a simple website, or whatever suits your fancy.

---

Demo and documentation:

https://spacebook.app

🙋 💥 👩🏽‍🚀 🚀 👨‍🚀 🛰️

---

Contributing

If you want to contribute or make fixes to spacebook, it is best to fork this repository directly and submit pull requests against it. If you spot a typo on the demo/documentation site, you can also open a fork directly from the edit button on the top of each page.

Install spacebook

If you want to quickly install for local testing follow the instructions below:

Requirements

You must be running Node version 12 or higher due to the Tailwind 2.0 release. I recommend using NVM to easily manage your Node versions if you need to switch back and forth between older versions.

• Node
• NVM (optional)

To find your current node version:

node --version

Step one

git clone https://github.com/broeker/spacebook

Step two

Install the site and run an initial build command:

cd spacebook

npm install

npm run build (only necessary the first time!)

If you get errors here, double check your node version!

Step three

Now spin up your local server to see your site!

npm run start

This command will start a local server and you'll be able to work on your site with hot reloads and some nice Browsersync features. 💥

---

spacebook's Issues

NetlifyCMS uses "pages" instead of "content/pages"

Describe the bug
When editing from NetlifyCMS, the Pages collection is set up to use the folder pages instead of content/pages. So it doesn't let us edit pages already in content/pages and it creates new pages in pages which only contains the HTML code generated from the body field.

To Reproduce
Steps to reproduce the behavior:

1. Quick launch link to Deploy to Netlify.
2. In Netlify, enable Identity and Git Gateway. Send an invite to your email and setup a password.
3. From GitHub, edit _data/site.json and set "enableNetlifyCMS" to true.
4. Access NetlifyCMS.
5. Check Pages collection. It will be empty.

Expected behavior
I expected to be able to edit existing pages and create new pages which should properly.

Screenshots

A couple more Dark Mode Styling Issues

Footer Nav Links

The footer nav links are not visible on hover:

I fixed these with a new rule in tailwind.css:

 .prose .footer-nav a:hover {
    @apply dark:text-pink-200 !important
  }

Search Box Input Text

The search text is not visible when typing:

I fixed these with a new rule in tailwind.css:

 input {
    @apply dark:text-gray-300
  }

npm install creates errors - I am using node v16.7.0

Describe the bug
I cloned the repo locally then typed "npm install" as stated in the directions.

To Reproduce
This is the ERR output from my debug.log file ...

3863 info run [email protected] install node_modules/sharp (node install/libvips && node install/dll-copy && prebuild-install) || (node-gyp rebuild && node install/dll-copy)
3864 info run [email protected] install node_modules/eleventy-plugin-lazyimages/node_modules/sharp (node install/libvips && node install/dll-copy && prebuild-install --runtime=napi) || (node-gyp rebuild && node install/dll-copy)
3865 info run [email protected] install { code: 0, signal: null }
3866 timing build:run:install:node_modules/sharp Completed in 1138ms
3867 info run [email protected] install { code: 1, signal: null }
3868 timing reify:rollback:createSparse Completed in 1170ms
3869 timing reify:rollback:retireShallow Completed in 0ms
3870 timing command:install Completed in 12061ms
3871 verbose stack Error: command failed
3871 verbose stack at ChildProcess. (/usr/lib/node_modules/npm/node_modules/@npmcli/promise-spawn/index.js:64:27)
3871 verbose stack at ChildProcess.emit (node:events:394:28)
3871 verbose stack at maybeClose (node:internal/child_process:1064:16)
3871 verbose stack at Process.ChildProcess._handle.onexit (node:internal/child_process:301:5)
3872 verbose pkgid [email protected]
3873 verbose cwd /home/deb/VMShares/My Projects/Documentation Site Generators/spacebook
3874 verbose Linux 5.13.12-1-MANJARO
3875 verbose argv "/usr/bin/node" "/usr/bin/npm" "install" "[email protected]"
3876 verbose node v16.7.0
3877 verbose npm v7.21.0
3878 error code 1
3879 error path /home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp
3880 error command failed
3881 error command sh -c (node install/libvips && node install/dll-copy && prebuild-install --runtime=napi) || (node-gyp rebuild && node install/dll-copy)
3882 error make: Entering directory '/home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp/build'
3882 error CC(target) Release/obj.target/nothing/../../../node-addon-api/nothing.o
3882 error AR(target) Release/obj.target/../../../node-addon-api/nothing.a
3882 error COPY Release/nothing.a
3882 error TOUCH Release/obj.target/libvips-cpp.stamp
3882 error CXX(target) Release/obj.target/sharp/src/common.o
3882 error make: Leaving directory '/home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp/build'
3883 error info sharp Using cached /home/deb/.npm/_libvips/libvips-8.9.1-linux-x64.tar.gz
3883 error gyp info it worked if it ends with ok
3883 error gyp info using [email protected]
3883 error gyp info using [email protected] | linux | x64
3883 error gyp info find Python using Python version 3.9.6 found at "/usr/bin/python3"
3883 error (node:36175) [DEP0150] DeprecationWarning: Setting process.config is deprecated. In the future the property will be read-only.
3883 error (Use node --trace-deprecation ... to show where the warning was created)
3883 error gyp info spawn /usr/bin/python3
3883 error gyp info spawn args [
3883 error gyp info spawn args '/usr/lib/node_modules/node-gyp/gyp/gyp_main.py',
3883 error gyp info spawn args 'binding.gyp',
3883 error gyp info spawn args '-f',
3883 error gyp info spawn args 'make',
3883 error gyp info spawn args '-I',
3883 error gyp info spawn args '/home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp/build/config.gypi',
3883 error gyp info spawn args '-I',
3883 error gyp info spawn args '/usr/lib/node_modules/node-gyp/addon.gypi',
3883 error gyp info spawn args '-I',
3883 error gyp info spawn args '/home/deb/.cache/node-gyp/16.7.0/include/node/common.gypi',
3883 error gyp info spawn args '-Dlibrary=shared_library',
3883 error gyp info spawn args '-Dvisibility=default',
3883 error gyp info spawn args '-Dnode_root_dir=/home/deb/.cache/node-gyp/16.7.0',
3883 error gyp info spawn args '-Dnode_gyp_dir=/usr/lib/node_modules/node-gyp',
3883 error gyp info spawn args '-Dnode_lib_file=/home/deb/.cache/node-gyp/16.7.0/<(target_arch)/node.lib',
3883 error gyp info spawn args '-Dmodule_root_dir=/home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp',
3883 error gyp info spawn args '-Dnode_engine=v8',
3883 error gyp info spawn args '--depth=.',
3883 error gyp info spawn args '--no-parallel',
3883 error gyp info spawn args '--generator-output',
3883 error gyp info spawn args 'build',
3883 error gyp info spawn args '-Goutput_dir=.'
3883 error gyp info spawn args ]
3883 error gyp info spawn make
3883 error gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
3883 error : warning: "_GLIBCXX_USE_CXX11_ABI" redefined
3883 error : note: this is the location of the previous definition
3883 error ../src/common.cc:22:10: fatal error: napi.h: No such file or directory
3883 error 22 | #include <napi.h>
3883 error | ^~~~~~~~
3883 error compilation terminated.
3883 error make: *** [sharp.target.mk:137: Release/obj.target/sharp/src/common.o] Error 1
3883 error gyp ERR! build error
3883 error gyp ERR! stack Error: make failed with exit code: 2
3883 error gyp ERR! stack at ChildProcess.onExit (/usr/lib/node_modules/node-gyp/lib/build.js:194:23)
3883 error gyp ERR! stack at ChildProcess.emit (node:events:394:28)
3883 error gyp ERR! stack at Process.ChildProcess._handle.onexit (node:internal/child_process:290:12)
3883 error gyp ERR! System Linux 5.13.12-1-MANJARO
3883 error gyp ERR! command "/usr/bin/node" "/usr/lib/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
3883 error gyp ERR! cwd /home/deb/VMShares/My Projects/Documentation Site Generators/spacebook/node_modules/eleventy-plugin-lazyimages/node_modules/sharp
3883 error gyp ERR! node -v v16.7.0
3883 error gyp ERR! node-gyp -v v8.1.0
3883 error gyp ERR! not ok
3884 verbose exit 1

Expected behavior
I was expecting spacebook to install correctly.

Thank you.

spacebook as just a docs generation tool

Is your feature request related to a problem? Please describe.
Just a feature, not a problem.

Describe the solution you'd like
I am looking for a docs generation tool (a minimal version of yours) without any cms integration

Describe alternatives you've considered
gitbook-cli, docusarus are the options I tried for converting md into docs site.

Additional context
I just want to use eleventy to make it as simple as possible, but instead of writing css and layout for sidebar, thought of using a template. Would be good if you publish a minimal variant just for docs generation

Turning Spacebook into a PWA

I apologize in advance if this is simple - relatively new to 11ty and PWAs.

I'm trying to add the web manifest reference to the generated HTML files sections. I assume spacebook has some template that 11ty uses to make the HTML - where would I go to inject the manifest reference?

Thank you

Menu triggered by hamburger not sticky

Describe the bug
In my mobile browsers (tried Firefox and Edge on Android) the vertical menu that appears when tapping the hamburger is anchored to the top rather than sticking to the viewport. This is really confusing when scrolled down the page because it seems as if the hamburger does nothing.

To Reproduce
Steps to reproduce the behavior:

1. Go to any page on mobile
2. Tap on hamburger menu
3. Scroll down the page
4. See error

Expected behavior
Menus should stick to viewport

Screenshots

custom themes for spacebook

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is.
I am always frustrated working with new technologies and believe that spacebook is the solution to this thank you!
I am interested in learning how to create custom themes with this project. I am interested in getting my team to
work with this project and hopefully allow each team member to have a different theme for themselves.

Describe the solution you'd like
A clear and concise description of what you want to happen.

I would like to have a feature that would be a plugin of some sort to change the themes that are created specifically for this
project.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

I can also consider tutorials that would show someone going through creating the motions of creating a custom theme

Additional context
Add any other context or screenshots about the feature request here.

If there is already dedicated individuals out there then please share them below thanks.

Tailwind 3?

Hey, you need help bumping tailwind to v3? :)

Password prompt visible after login

After logging in into a password protected Spacebook, the password prompt is stil visible. Sometimes at the bottom en sometimes in the middle of the page.

Steps to reproduce the behavior:

1. Go to https://deploy-preview-10--spacebook-app.netlify.app/

2. Scroll down to see
   

3. See password prompt

Checked in Chrome 99

Throws an error on MacOs Ventura

Describe the bug
Everything worked as expected, until I upgraded the MacOS version from Monterey to Ventura. Running npm start in iTerm2 to run the site locally outputs an error:

> eleventy --serve & postcss styles/tailwind.css --o _tmp/style.css --watch

Eleventy fatal error: (more in DEBUG output)
> Error in your Eleventy config file '/Users/____/___/_________________/.eleventy.js'.

`EleventyConfigError` was thrown
> 'darwin-x64' binaries cannot be used on the 'darwin-arm64v8' platform. Please remove the 'node_modules/sharp' directory and run 'npm install' on the 'darwin-arm64v8' platform.

Removing the 'node_modules/sharp' directory and running 'npm install', as directed in the error message, changes nothing.

Pushing changes to Netlify still builds the site on the web without errors.

To Reproduce
Steps to reproduce the behavior:

1. Upgrade MacOS from Monterey to Ventura.
2. In iTerm2, cd to spacebook directory
3. run npm start

Expected behavior
npm start builds the site with its new changes (if any), starts a server locally, and outputs a localhost address to the terminal, with which to see the changes to the site in the browser.

Screenshots

Additional context
MacBook Pro 16-inch, 2021, Apple M1 Max, Ventura 13.0.1
iTerm2 3.4.16 using zsh and fig

Parent is required when editing in Netlify CMS

Describe the bug
When trying to publish a page with top-level navigation, the parent field is required when publishing via Netlify CMS, preventing it from getting published/saved.

To Reproduce
Steps to reproduce the behavior:

1. While logged into the Netlify CMS, edit a top-level page or create a new page that will not have a parent.
2. Click on the 'Publish' button in the top-right corner.
3. See input validation that a parent is required, preventing the page from being published.

Expected behavior
The parent field should be optional. When no parent is provided, the eleventyNavigation parent property should not be present at all in the .md file (this is the case with existing top-level pages like "Getting Started").

Screenshots

I can attempt a fix and create a PR if this is not a priority since it is a big hassle with some of my current projects. Thank you for your work!

Link to markdown tags returns 404

Describe the bug
The documentation page https://spacebook.app/getting-started/content/#adding-your-content has the paragraph starting "Your content can include all sorts of markdown tags..." with a link to https://spacebook.app/markdown but this returns a 404 error.

Dead link in the doc

Hello there,

on the page https://spacebook.app/tips-and-tricks/editing/ there is a link about Netlify, pointing to https://spacebook.app/netlifycms . This page is 404

The right URL may be https://spacebook.app/advanced/netlifycms/

Custom links in TOC

Is is possible to set a link to a foreign website in the "table of contents" (left menu)?
Thanks a lot!

Table head colour does not contrast with darkmode enabled

Table head content does not inherit the lighter colour when dark mode is enabled

To Reproduce
Add a table to a page

Test content	This is not visible in dark mode
Content	This content is visible in dark mode

Expected behavior
The table head follows the behaviour of the table and inherits the lighter colour when dark mode is enabled

Screenshots

Enable dark mode by default

First of all, thanks for sharing this project! It's the best Elventy starter I've seen, love it!

Describe the solution you'd like

I was wondering if it's possible to add an option to enable darkMode as the default.

Setting <body class="dark"> in the base template does not work as expected as the current implementation removes that class when the darkmode item is not found in localStorage.

  if (localStorage.getItem('darkmode') === 'true') {
    document.body.classList.add("dark");
  } else {
    document.body.classList.remove("dark");
  }

Describe alternatives you've considered

The above logic can probably be tweaked a bit so it allows for setting a default, happy to give a go at fixing it.

Sitemap.xml

Is your feature request related to a problem? Please describe.
For public sites, it would be nice to generate a sitemap.xml file

Streamlined starter content

Is your feature request related to a problem? Please describe.
Right now when you create a new spacebook it brings over all of the spacebook.app content -- this should be simplifed to a single welcome page.

EmbedEverything plugin does not work for Instagram

Describe the bug
Putting an Instagram URL on its own line in markdown does not embed it.

To Reproduce
Steps to reproduce the behavior:

1. Paste the URL into the markdown file.
2. The URL is rendered as a link instead of an embedded image/link.

Expected behavior
The current markdown rendering seems to take any URL (even if the http / www is omitted) and wrap it in an <a> tag whereas embed-everything requires the Instagram URL to be by itself wrapped in <p> tags. It may not be something that can be fixed / tweaked if it's core to 11ty.

Fixed: Browser Compatibility: Safari, Firefox iOS

1. In Safari and certain browsers, the light bulb icon doesn't render properly; it remains a default black icon instead of turning yellow when dark mode is on and gray when dark mode is off.

   

   For this issue, under header.njk line 24, moving class="text-gray-400 hover:text-yellow-400 dark:text-yellow-400" from the path to the svg tag seems to fix the issue with the rendering in Safari.

2. In Firefox on iOS, the dark and light modes are inverted. The font color scheme for dark mode is used for light and vice versa.

   

   A solution is to make sure that night mode is turned off under Firefox iOS menu. Instead use Theme under Settings to set light and dark mode.

Netlify functions

Is your feature request related to a problem? Please describe.
Spacebooks are all set to run Netlify Functions (AWS Lambda) and it would be nice to provide even a Hello World example for advanced use cases.

Backlinks support

Hi I am not sure whether it is a question or a feature request.

I need a backlinks support for a static documentation site. I found https://github.com/binyamin/eleventy-garden which implements the support. However the eleventy-garden doesn't have other features which are present on spacebook. So I tried to port the support into spacebook. Unfortunately I am not up to speed with eleventy to do it. Are there any plans to support backlinks? How hard it is?

Change Tailwind CSS

I was trying to fix a problem with the style for the navigation links: In dark mode on hover, they are too dark to see.

I found a rule in styles/tailwind.css and applied a change:

  nav ul li a:hover {
    @apply text-gray-900 dark:text-gray-100;
  }

But it's not applied after running npm start. In fact, I can delete the file and it doesn't matter.

So, how can I update the CSS?

a footer nav are not inline, and the left < has an incorrect orientation

Describe the bug
a footer nav are not inline, and the left < has an incorrect orientation
(I cannot find ,rotate-180 in style.css )

To Reproduce
Steps to reproduce the behavior:

1. create a fresh repo
2. create a few new pages
3. observe footer nav

Expected behavior
Footer nav items should be inline

Screenshots

Flash of Unstyled Content (FOUC)

Is your feature request related to a problem? Please describe.
On encrypted sites, there is still a single flash of unstyled content that appears on first page load. (After that, there is a page loader/spinner that works nicely.) It would be nice to eliminate this initial FOUC.