QuickStart could offer more initial structure

[onlyhavecans]

I was just testing FRESH install for a quick site and noticed the quick start only offers a src folder with NO contents. It might be more of a jumpstart for knew user to have the quick start build something like this in src

src
|-> pages
    |-> 404.rst (shows an example of a hidden page)
    |-> About.rst (Offers up a quick and dirty about page with all applicable metadata)
|-> static
|-> TestCategory
    |-> ExamplePost.rst (A placeholder post with all standard metadata that the user can delete or turn into a template for their blog)

I know there is already the "samples" in the main installer... but your most basic user isn't going to fork the code, they are going to easy_install pelican

[almet]

I'm not sure we want this: while this is an interesting way to make users discover the features of pelican, it also means they will have more to deal with that the bare minimum. Maybe we could ask them some question in the quickstart script asking them if they want to have a page to handle 404, etc.

[onlyhavecans]

My only worry is that we could end up with the 'clippy' effect where the users is banging return for the sake of it and telling the program to get on with it... I think a quick delete command is faster that reading through X prompts.

Another way of doing it is adding an "expert" option/flag to the quickstart that only gives the empty src and streamlines a few things. Honestly though, someone who generates that many new sites will likely have their own template to use.

[almet]

well, the problem is that it's now faster to write your own settings that running the quick start, so it's not really "quick" anymore, is it?

We could probably add flags to the quickstart script so it generates everything fro mthe values we give it, also that could be cool to add this expert flag, yep.

[wrl]

just wanted to throw my 2 cents in here.

did a pelican-quickstart this afternoon to play with it and was immediately confused as to why "make devserver" wasn't running, but quickly realized that it was because i hadn't created a post yet. doubly confusing is that the devserver doesn't like this situation but "make html" is fine with it.

also this is the first i'm finding out about the "samples" directory, which i will be sure to check out. however, i have to get it from git, because i did indeed install with pip.

[onlyhavecans]

@ametaireau I think it's only quicker for us. For someone launching Pelican for the first time after installing it from pip... I think we should give them a running head start.

I think that maybe by default it should hand out a bunch of hand holding, default posts showing off pelican, a config full of coments, etc, etc... but maybe an --expert or --quicker flag to just give the base it takes to toss up a blog like we do now.

[justinmayer]

For the record, the relevant documentation clearly states that content must be added first (emphasis mine):

Once you finish answering all the questions, you can begin adding content to the content folder that has been created for you. (See Writing articles using Pelican section below for more information about how to format your content.) Once you have some content to generate, you can convert it to HTML via the following command...

That said, we could add a question to the quickstart script that asks the user whether sample content is desired. I don't think that should be the default, nor do I think the user should have to pass an --expert flag if the user doesn't want the sample content. If users can't manage to choose "Yes" when asked whether sample content is desired, I don't think any amount of extra hand-holding is going to help.

If the user answers "Yes", we'll need access to the sample content. Perhaps we should change the installation process such that the samples folder is installed to [...]/lib/site-packages/pelican/ during install via setup.py, pip, and easy_install. That way, if the user answers "Yes", the script can just copy that folder over.

Moreover, if the user answers "No" to that question, we could add a message to the end of the quickstart script that says something like:

Please keep in mind that you'll need to add some post content before doing anything else. Subsequent commands (e.g., make html, make devserver, etc.) will fail if you do not.

I think something along the lines of the above should ameliorate much of the potential confusion.

[onlyhavecans]

I like your idea better than mine @justinmayer As an aside/thought we might want to clean up the samples folder a little.

[justinmayer]

This issue has been open for a year. Unless someone offers to step forward to address it, my inclination is to close the issue by the end of this week.

[epogrebnyak]

@ametaireau I think it's only quicker for us. For someone launching Pelican for the first time after installing it from pip... I think we should give them a running head start.

New user here - I think pelican is very exciting and offers great possibilities for a python user and a lover sphinx readthedoics theme, invoke works on Windows and many things soled so nicely, except the quickstart and getting a "Hello, world!" example running. I think it is a barrier for new users.

My path:

• installed pelican via pip
• tried inv somehting, nice, works in Windows!
• run a quickstart (ah, reminds of sphinx quickstart, cool!)
• run inv livereload
• saw an empty theme at localhost
• decided on adding somehting to content folder, like... echo Hello, I'm index file > index.md
• nothing happens, back to the docs
• docs say: The next step is to begin to adding content to the content folder that has been created for you.
• ok, next page has a bit diluted (not clear what is a must and what is enhancement) information about what content should look like and a link to sample folder.
• copying some examples from sample folder still no effect, eg curl https://raw.githubusercontent.com/getpelican/pelican/master/samples/content/article2.rst > content/article2.rst still not appearing
• got to be able to show something like pages / front.md, but not from root, learned from error message title meta is mandatory
• still no luck getting to show anything from root of content folder

This moment is a bit frustrating, as the user feels stupid here and not knowing what to do next.

In mkdocs, mdbook, hugo the very same me was able to edit or add new content, but not on pelican. I'm writing this not as a complaint, but as to descrive a gap in user workflow / docs / maybe fucntionality.

Ideas to fix things:

1. Populate content with a few files as result as result quickstart creation.

@justinmayer said he was not favoring the above, so other options are

2. Give a complete working setup (fodler strucure, file contents) in documentation before going into details of adding extra metadata at https://docs.getpelican.com/en/stable/content.html

3. Provide a minimal example site as separate folder or repo.

4. This is a whole round of work and planning, but maybe consider new / new blog / new article commands, similar to Hugo. I do not quite like their implementation (use must know and specify the path before invoking new), but at least the possibility is there.

I can add PR's to either of these once/if this gives a go, but before that I would also like to learn what it takes for my poor content/index.md to get processed by pelican.

[avaris]

Give a complete working setup (fodler strucure, file contents) in documentation before going into details of adding extra metadata at https://docs.getpelican.com/en/stable/content.html

Provide a minimal example site as separate folder or repo.

Isn't this already in the docs/repo?

"You can find sample content in the repository at samples/content/."

i.e.: https://github.com/getpelican/pelican/tree/master/samples/content

[epogrebnyak]

Isn't this already in the docs/repo?

"You can find sample content in the repository at samples/content/."

i.e.: https://github.com/getpelican/pelican/tree/master/samples/content

@avais, samples/content does not have a single markdown file to draw example from, it takes trial and error to come up with a rule that title and date are mandatory tags.

Also samples/content currently works as collection of formatting examples, not as a clean minimal setup.

Examples to consider:

• https://github.com/gohugoio/hugoBasicExample/tree/master/content has a minimal working site example, same for exampleSite folders by theme
• https://rust-lang.github.io/mdBook/cli/init.html provides two files in intial setup (both as init command and follows through documentation)
• https://www.mkdocs.org/#adding-pages ensures you can add a single file and see it rendered (documentation)

[justinmayer]

@epogrebnyak: Thank you for taking the time to provide such detailed feedback. Much appreciated. You said:

@justinmayer said he was not favoring the above

I did? Re-reading my comment from January 2013, what I said is that I don’t think example content should generated by default, but that it could be provided by answering “yes” to a corresponding new quick-start question.

I would like to work on this when I can find the time. At a minimum, I will create an example site in a separate repo. I may then also add a question to the quick-start that offers to download the contents of that repo to the user’s newly-created site.

As for adding a command to create new articles/pages, that issue (#1410) and pull request (https://github.com/getpelican/pelican-tools/issues/6) already exist and are in process.

[epogrebnyak]

I did? Re-reading my comment from January 2013, what I said is that I don’t think example content should generated by default, but that it could be provided by answering “yes” to a corresponding new quick-start question.

That's a detail I missed - opens door to generating a sample website based on an option/quickstart answer, which I think is a great scenario for new users.

I thought of making a separate repo with minimal example, to learn pelican myself - maybe can be a draft for a standard example, in some way (I wish I knew Pelican better). Or maybe anyone can point to well-structured sites authored with pelican to be an example? https://blog.getpelican.com/ itself?

Should we provide both blog and article examples - so that the a blogging usercase and documentation usecase are covered, in the same folder?