search

Pelican-Elegant / elegant

Best theme for Pelican Static Blog Generator
https://elegant.oncrashreboot.com/
MIT License
295 stars 187 forks source link

Add categories #314

Closed talha131 closed 5 years ago

talha131 commented 5 years ago

Currently we have all articles filed under "Elegant - Pelican Theme". Originally documentation was hosted at my personal blog. It made sense to file everything under "Elegant" category.

But this needs to be expanded now. Off the top of my head

  1. Configuration
  2. Guides (It will have articles on integrating plugins with the theme)
  3. Customization
  4. Analytics

Suggestions and PR are welcomed.

silverhook commented 5 years ago

This sounds like a good overview, yes.

Are these already pages or blog entries?

In any case, it might make sense to add a blog for releases (and big announcements).

talha131 commented 5 years ago

We need to change meta data of existing articles.

Announcement articles are good suggestion. We can write release notes articles and file them under "Announcement" category.

silverhook commented 5 years ago

Another good category would be “Release notes”. Especially for people who would only want to follow our releases, and nothing else.

I’ll add it for #52, if no-one complains.

talha131 commented 5 years ago

Thanks @silverhook. Yeah, "Release Notes" category is fine. It's more apt for #52 than "Announcement" category.

silverhook commented 5 years ago

Should we re-order the categories as folders, for easier navigation?

Currently the categories are explicitly stated in the MarkDown files, but we could just create the appropriate folders and move them there.

talha131 commented 5 years ago

Yes. You are right. Each category should get its folder. Currently it isn't b/c its originally from my blog which placed all elegant related material inside elegant folder.

silverhook commented 5 years ago

To recap, we have two options:

All blogs

One option would be to keep everything as articles and have the following categories (separated as folders):

Blogs and pages

Or have pages and blogs entries separated:

Blog entries for stuff where the publication date is useful info:

Pages, where publication date is not a relevant piece of info, or even counterproductive (e.g. people think that configuration page is outdated):

iranzo commented 5 years ago

@talha131 as it is now under documentation/content and then subfolders I think this can be closed

talha131 commented 5 years ago

Right. I did add some folders in docs repo.

silverhook commented 5 years ago

The articles are still in wrong folders. Reopening.

talha131 commented 5 years ago

This is our next branch

https://github.com/Pelican-Elegant/elegant/tree/next/documentation/content

New categories have been added, articles moved and extracted. Please point out specifically which articles are in wrong folder.

silverhook commented 5 years ago

Will provide a PR in the next days, I hope.

talha131 commented 5 years ago

@silverhook I have moved around the articles. Kindly checkout the latest release. And let me know if I missed something. If not then please close this issue.

silverhook commented 5 years ago

Has anyone thought about how this would look if we moved a lot of this into pages (instead of blog posts)?

talha131 commented 5 years ago

@jackdewinter feel free to share you feedback.

@jackdewinter had shared some ideas about categories with me via email. This gist was that

  1. We have too many categories
  2. We should have clear categories so that new user would know in which section he would find the relevant help article

Has anyone thought about how this would look if we moved a lot of this into pages (instead of blog posts)?

@silverhook well @jackdewinter has been working on a 101 help article. The idea is to have one or few more articles for absolute beginners. These 101 article(s) will point user to the detailed help articles.

Here is one such article

https://elegant.oncrashreboot.com/unique-home-page-features

There was a suggestion of creating a new 101 category. But perhaps we can instead create a page for 101 article.

Lets see what @jackdewinter has to say about it.

silverhook commented 5 years ago

We have too many categories We should have clear categories so that new user would know in which section he would find the relevant help article

I agree on both fronts. Looking forward to @jackdewinter’s feedback here.

talha131 commented 5 years ago

Continuing discussion from https://github.com/Pelican-Elegant/elegant/pull/452

Moving files into folders is not enough for changing the category. You will have to change the category too

It should be enough to have just one or the other, having both seems to cause needless confusion and duplication. In that case I would suggest we simply strip the category field from the posts and categorise by folders, as this would be much easier to manage when the articles start piling up.

  1. Folders do not work as categories because we have set USE_FOLDER_AS_CATEGORY to false
  2. Folders are not suitable to work as categories. Folders depend on file system. You know well file system does not allow certain special characters to be used as name. Therefore, we will never be able to use those characters in our categories
  3. Using Folders means if we have a category in Chinese or RTL like Arabic, it will not appear nicely inside the terminal. (I have experienced it first hand with Urdu and Arabic folder and file names)
  4. Using folders means, to change a category we have to move file. Git does not work nicely with move and renames even if --follow option, so I am warry of renaming and move files

I’m confused with the Development category. The articles there all seemed to be about how to deploy (in a CI/CD manner) Pelican and Elegant, not about how to contribute to the project (which has its own category) or develop it further locally. In the end we could also just have “Miscellaneous” as a catch-all for whatever we can’t categorise otherwise.

I agree. Currently we have only two articles in Development category. @iranzo wrote them. At that time we used them for our CI. We can either move them to

  1. Miscellaneous
  2. Or to Contributing category and specify that these tips are no longer used.
talha131 commented 5 years ago

Lets take one thing at a time.

Item 1

Which category best suits for the two articles present in Development category?

My suggestion

  1. Move them to Contributing
  2. Delete Development folder
  3. Add note inside those two articles that Elegant CI does not used them anymore.

Item 2

Should we remove all the folder inside content folder?

I have been thinking of removing all the folders from content folder.

Why?

  1. Folders confuse contributors to think that the serve as categories which isn't true
  2. Internal linking will become easier
  3. If you rename a folder then you have to search for its usage in all the Markdown files and rename it too. If we remove folders then we will not have worry about it

Why not?

  1. If you have lots of files in a folder, then Github website does slows down and in some cases refuses to show the contents

I am in between.

Item 3

Lets take one category at a time and fix it.

Starting with Monetization.

Is everyone okay with it?

  1. Does it need to be rename?
  2. Do we need to move article out from it?
  3. Do we need to add an article to it?
iranzo commented 5 years ago

Rename files to contain category-topic but remove folders or just all in same folder.

Easier to grep, sed, etc

Sent from mobile

El sáb., 20 jul. 2019 9:58, Talha Mansoor notifications@github.com escribió:

Lets take one thing at a time. Item 1

Which category best suits for the two articles present in Development category?

My suggestion

  1. Move them to Contributing
  2. Delete Development folder
  3. Add note inside those two articles that Elegant CI does not used them anymore.

Item 2

Should we remove all the folder inside content folder?

I have been thinking of removing all the folders from content folder.

Why?

  1. Folders confuse contributors to think that the serve as categories which isn't true
  2. Internal linking will become easier
  3. If you rename a folder then you have to search for its usage in all the Markdown files and rename it too. If we remove folders then we will not have worry about it

Why not?

  1. If you have lots of files in a folder, then Github website does slows down and in some cases refuses to show the contents

I am in between. Item 3

Lets take one category at a time and fix it.

Starting with Monetization.

Is everyone okay with it?

  1. Does it need to be rename?
  2. Do we need to move article out from it?
  3. Do we need to add an article to it?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Pelican-Elegant/elegant/issues/314?email_source=notifications&email_token=AACMJD4KJ65DVNVQDJXTPKLQALASHA5CNFSM4HWMJ2MKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD2NJGCA#issuecomment-513446664, or mute the thread https://github.com/notifications/unsubscribe-auth/AACMJD3RIHKIYO7RPUMZ24TQALASHANCNFSM4HWMJ2MA .

talha131 commented 5 years ago

Rename files to contain category-topic but remove folders or just all in same folder.

If we rename files to contain category topic then we will again have to rename files whenever we change the category.

I lke "just all in the same folder", regardless of category idea.

jackdewinter commented 5 years ago

Thoughts?

talha131 commented 5 years ago

Item 1: Am I missing something? The only thing in that directory that I can see is the new status doc?

Probably due to merge conflicts, those articles have moved to "Deployment and CD folder", though their categories have not changed.

Item 2: I like putting things in one directory, but concerned about all 57 articles being in the one directory.

So you agree. @iranzo has already liked the idea. Now lets see what @silverhook has to say.

Instead of Monetization, I would like to see a category named "Advanced Concepts?" with Monetization, Mailing List, Analytics and Deployment. From my point of view, once you have your web site set up, these are things you want to do to make it go further.

I disagree. Look, if we have 2, 3 or more articles that have a common theme, we should move them together. All articles under monetization (plus a possibility of adding AdSense) are clearly on the same topic.

I do think, we can change "Monetization" to something easier like "Earn Money From Your Site". Monetization sounds kinda technical.

Goal is not to reduce categories for the sake of reduction or to add them just cause we like new categories. Goal is to help user find them. Montization is such a clear category that I don't think it should be merged.

Also, add an article on setting up a sitemap and robots.txt to make the SEO work better.

Agree. We need better instructions for it.

jackdewinter commented 5 years ago

Here are my notes from taking a look at Categories. My big takeaway: In my opinion, we should define better Categories and Tags. This means clearly identifying what is a category and what is a tag.

From there, it is a question of organizing it so that someone can find things. So I asked myself some basic questions about various things in the documentation:

NOTE: Rough proposal: just a starting point

talha131 commented 5 years ago

Jack,

I read your comment on Github. Before we proceed, let me share my ideas with you.

We will end up with 7 categories. (plus 1 or two more if I have overlooked something.)

Analytics, SEO and SMO

We will merge Analytics and "SEO & SMO" into it.

One less category.

Components

This category will contain all the articles about components we use like

  1. Table of Conents
  2. Subtitle
  3. Tables (to be written)
  4. Warnings and Admonition
  5. Code snippets
  6. Footer
  7. Landing Page

3 categories are removed with this

Connect with your readers

This needs a better title.

  1. Comments
  2. News Letter
  3. Social Links

It will reduce one category.

Earn money from your blog

This needs a better title.

This means renaming Monetization to "Earn money from your blog".

Advanced

  1. Search
  2. 404
  3. Extra customizations
  4. Fav icons
  5. Article redirection

Contributing

  1. Merge Design Philosophy into it.
  2. Merge development into it

Release Notes

  1. Keep it
jackdewinter commented 5 years ago

Existing pages that I don't see referenced in your list:

Category Names:

Categories:

talha131 commented 5 years ago

@jackdewinter thank you for being so thorough.

modified-date.md

advanced

page-title.md

components

web-safe-fonts.md

components

author-blurbs.md

suported plugins

change-labels.md

advanced

meta-data.md

advanced

reading-time.md

Supported Plugins

Taxonomy category

Components

Category Names:

Good suggestions. Agree.

I am slight concerned that merging Design Philosophy in to Contributing will hide it from people that are looking for an answer to "why did they do it that way?"

I agree but that's the only category it can fit. I don't think we are going to add more articles to "Design Philosophy".

Moreover, if a contributors feels like changing the style, he is more likely to look it up under "Contributing" category.

So in conclusion, "Contributing" would do fine.

talha131 commented 5 years ago

I will make these changes.

I also need to add a test for broken links so that if links are dead due to migration, we would know.

jackdewinter commented 5 years ago

It looks like we have supported plugins again. Am I reading that correctly? If so, and it's the Plugin category or another category, which one wins? An example of that is TOC, where we need the extract_toc plugin to be able to move it.

Other than that... "Advanced Features" instead of "advanced"?

talha131 commented 5 years ago

It looks like we have supported plugins again. Am I reading that correctly?

Yes. We have.

An example of that is TOC, where we need the extract_toc plugin to be able to move it.

It should go into "Components" category. Because user cannot use extract plugin unless he is interested in TOC.

Similarly user needs "tipue" plugin for search to work. It will stay in "Advanced feature" b/c user cannot possibly need tipue plugin without search feature.

So in these cases, user is expected to look for feature, rather than the plugin.

If you have doubts, then we can use subtitle, i.e. mention plugin in the subtitle of the article.

Other than that... "Advanced Features" instead of "advanced"?

Agree.

talha131 commented 5 years ago

:tada: This issue has been resolved in version 4.0.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: