Very confused by the docs

[on3iro]

Question

Hey guys, I just wanted to get started with spectacle, but the docs are confusing me quite a bit.
These are the issues i am having:

1. "Getting Started with Development" - this paragraph tells me, that all my source files have to be inside the src/ dir. So far so good. But this also reads a bit like there should already be such a directory after installing spectacle with yarn/npm. I assume spectacle just wants me to create src myself? Edit: My bad - i completely missed the Getting Started section. It might be benefitial to move Getting Started before Basic Concepts.
2. The next part tells me to start a development server with ominous npm-scripts which are not yet part of my package.json. Instead I should look inside examples/js - I realize these are part of the spectacle repository. But how am I supposed to access these just after running yarn add spectacle? Ofcourse I could look inside my node_modules, but is this what you want users to actually do?
3. Is there a way to use spectacle with multiple markdown or even js/jsx files? I can't seem to find anything inside the docs

Thanks in advance :)

[kale-stew]

Hi Theo! Thanks for opening this issue. We spent a lot of time rewriting these docs and issues like these help us better understanding where we might have missed our mark. 🙂

1. It seems like our use of the phrase "Getting Started" in two places is confusing. The "Getting Started with Development" paragraph you initially refer to here is about developing against the Spectacle src. I agree, this blurb should probably be moved into a Contributing section or somewhere else, where it's more obvious that this is about the dev process and not deck creation. If you navigate to "Getting Started" (second from the bottom in the lefthand navigation), you will find the tutorial we wrote to introduce newcomers to the library.

2. By "the next part" are you referring to the "Writing Your Presentation" sub section? We did link to the spectacle-cli repository and documentation directly in this section, but I understand if the link decoration wasn't obvious at first read. We intended to make it more clear that use of spectacle-cli was just another option for developing with Spectacle, but it sounds like we missed that mark with our phrasing as well. To address the second half of your question here, it sounds like we should once again better indicate that "Getting Started: A Tutorial" will be your better bet for clear, step-by-step instructions, and not the "Basic Concepts" subsections.

3. I don't believe we have a process documented anywhere for using multiple markdown or jsx files, but I do know we have a couple of open issues surrounding imported slides (Custom Slides Ignored; Stepper Ignores Steps #871, Appear component does not function when placed in an MDX file #870) so we will need to resolve the existing bugs before we formalize a process around imported slides. I can spend some time on this today.

Hopefully I've addressed your concerns here, but please don't hesitate to ask more clarifying questions. Additionally, I will try to reorg our docs to make them more intuitive to navigate. I'm sure you're not the only one with these questions. 👍

[on3iro]

@kale-stew Hi Kylie - thanks a lot for the quick response.

Yeah, I think re-organizing the docs a little bit would make them definitely more intuitive to read. I suspected that the basic concepts section was more like a contribution section, but wasn't sure about it. I will definitely have a look at the issues you mentioned. I am currently transferring a huge amount of slides from a keynote into a spectacle presentation and putting everything into a single file makes organization really difficult.

A few more smalle questions:

1. Is there a way to apply a background color to multiple slides (I currently do use the basic deck which was created by running spectacle-boilerplate and modify it to my needs. However I could not seem to find a way to overwrite the default background color.)
2. Is it possible to apply styles to markdown slides?
   Edit: Oh I just realized, that text will by default have the secondary-color of the theme. Coincidentally I used this color as a background for the slide containing the markdown component. It would be really helpful, if there was a section inside the docs, specifying how theme props affect markdown. (or did it just miss that section?)
3. Am I correct, that the current stepper docs do not reflect how it actually works at the moment? The API does not specify the defaultValue prop, I find inside a freshly bootstrapped spectacle presentation. Furthermore the callback function seems to be different from the one shown inside the docs.

Thanks again :)

[on3iro]

@kale-stew one more question ;) - is there a way to define the default indentation level of <CodePane>s? Currently it looks like it indents a single space inside the presentation for each 2 spaces inside my actual code block, which is pretty annoying.

Actual Code:

Presentation:

[slorber]

Did you find a way to customize the background color easily using theme or template?

I don't find any solution, going to migrate to keynote just because of that :/

#938

[on3iro]

@slorber unfortunately I didn't (if I remember correctly - it's been a while since I last used spectacle)

[Zenahr]

I agree on how the docs are confusing to read. Thanks for opening this issue. I might look into contributing to the docs as well and maybe we could get it more streamlined for first-time users by seperating the docs into dev-docs and user-docs.

[jgoodall]

For customizing background color, I described how to do it here (short answer, use tertiary in theme file):
#938 (comment)