New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Blog Support roadmap #36

Open
chuckdries opened this Issue Apr 15, 2018 · 77 comments

Comments

Projects
None yet
@chuckdries

chuckdries commented Apr 15, 2018

Hello,

I'm excited to use vuepress for my personal website but I kinda want blog support before I switch, so I was thinking I'd kickstart that discussion on that now. This issue is to seek input as to what blog support might look like.

I was thinking a minimum viable product might be

  • some kind of tag/category system
  • An alternative default theme which feels more like a blog
  • helper utilities for themes (high order components?) for getting lists of posts around the tag/category system
  • Pre-defined markdown templates that correspond to theme vue components, like hexo's layouts
  • A CLI command for bootstrapping posts, vuepress new [layout] <post title>
@FadySamirSadek

This comment has been minimized.

Contributor

FadySamirSadek commented Apr 15, 2018

I think you should add also the functionality to publish only posts with dates that has already came like gatsby and jekyll. If you need help I would absolutely love to work on these tasks with you

@gaomd

This comment has been minimized.

gaomd commented Apr 15, 2018

  • RSS/JSON Feed
  • Draft post
  • Ability to eliminates the .html extension
  • Split date into subdirs: blog/2018-04-16-post-title.md => blog/2018/04/16/post-title/index.html
@mdaffin

This comment has been minimized.

Contributor

mdaffin commented Apr 15, 2018

The ability to alias posts and create redirects for them to allow movement of old posts while preserving all incoming links.

@ChinuxParibus

This comment has been minimized.

ChinuxParibus commented Apr 16, 2018

Maybe list all post in some sort of filter (customizable, of course), tags or categories and show them in README.md at first (chronologically or by tags).

This was referenced Apr 16, 2018

@Tsuki

This comment has been minimized.

Contributor

Tsuki commented Apr 17, 2018

vuepress eject with default config

@lekevicius

This comment has been minimized.

Collaborator

lekevicius commented Apr 17, 2018

I have been reading VuePress code and comparing with the blog build system I have written for Gulp.

List of features I have for my gulp static blog:

  • Markdown
  • Custom frontmatter
  • Per-post CSS and JS
  • Content in siteData to create feed, index page, etc.
  • RSS/JSON feed
  • Tags in frontmatter
  • Date parsing from filename
  • Virtual directories in URL, as described by @gaomd, turning 2018-04-16-post-title.md to blog/2018/04/16/post-title/index.html
  • Custom helper functions, like reading time calculation from markdown
  • Pagination for blog page
  • Paginated monthly archives
  • Paginated tag pages
  • Link-posts (like Daring Fireball, showing differently in feed if link frontmatter meta is found)

These are all the features I've built for gulp static site building, and would like VuePress to have.

However, adding all of that to the "core" would not be very great. I think a better, smarter solution would be to think of a way to allow themes to modify/plug into prepare and build stages, creating virtual pages, feed, etc.

I'm happy to help building and designing Blog theme, but I'd like to work out this build stage plugins before, instead of forking and modifying "core".

@mdaffin

This comment has been minimized.

Contributor

mdaffin commented Apr 17, 2018

Looks like it is reasonably easy to get lists of posts and filter tags/categories working even without support in the Layouts. Inside any .md file:

---
home: true
---
<div v-for="post in posts_with_tag('some_tag')"
     :key="post.frontmatter.date">
  <router-link :to="post.path">
    <article>
      <div class="title">{{ post.title }}</div>
      <div class="date">{{ new Date(post.frontmatter.date).toLocaleDateString() }}</div>
      <div class="description">{{ post.frontmatter.description }}</div>
    </article>
  </router-link>
</div>

<script>
export default {
    methods: {
        posts_with_tag(tag) {
            return this.$site.pages
            .filter((page) => page.frontmatter.tags)
            .filter((page) => page.frontmatter.tags.includes(tag))
        },
        posts() {
            return this.$site.pages
            .filter((page) => page.path.startsWith("/blog/"))
        }
    },
}
</script>

The only missing part is being able to generate dynamic pages, but I think this can be solved generically along with creating a sitemap, rss feed, specific tag/category pages, redirect links by allowing the theme or pages to add extra routes with plain text content or layouts with data. With something like add_route(route, payload, layout) or add_route(route, content) that the layout/pages can call on the fly for example when they detect a new tag.

@lekevicius

This comment has been minimized.

Collaborator

lekevicius commented Apr 17, 2018

Quite right. Generic features/building blogs needed:

  • Registering new routes in theme (for index, archives, tag pages, pagination)
  • Content, not only metadata, in siteData (for feed, index, archive pages)
  • URL rewriting for pages (transform .md filename to nice post URL)

With these building blogs, entire blogging system can be made 🎉

@mdaffin

This comment has been minimized.

Contributor

mdaffin commented Apr 17, 2018

@lekevicius I think those are the core features that are missing from vuepress, once those are added I believe that the rest of the features listed in this thread can be accomplished through the default or may be an alternitive them. It might be worth rasing them as seperate issues if the others agree?

@mdaffin mdaffin referenced this issue Apr 17, 2018

Closed

Add an RSS feed #3

@GabMic

This comment has been minimized.

GabMic commented Apr 18, 2018

A draft outosave system.

@yeedle

This comment has been minimized.

yeedle commented Apr 18, 2018

What about comments? A default theme should perhaps offer a commenting component that integrates one of the popular commenting platforms.

@yyx990803

This comment has been minimized.

Member

yyx990803 commented Apr 18, 2018

So - the default theme is going to be focused on documentation sites. Proper blog support should be done in a separate theme - and we currently don't have the bandwidth to work on that, so the goal in VuePress core should be designing the minimum API that can enable a custom theme to provide full blogging support. I'd encourage the community to explore that and provide feedback on what is currently lacking (e.g. this comment) and what kind of APIs would make that possible.

For registering additional routes, currently .vuepress/enhanceApp.js can get access to the router. I think we can allow a theme to do something similar. Idea: if a theme exposes index.js, it can do something similar to this:

// theme/index.js
export default ({ Vue, router, options }) => {
  router.addRoutes([
    {
      path: '/archive',
      component: () => import('./Archive.vue')
    }
  ])
}
@lekevicius

This comment has been minimized.

Collaborator

lekevicius commented Apr 19, 2018

@yyx990803 That would be great to solve route adding.

Would this also allow route rewriting, that is, transforming 2018-04-16-post-title (.md file) to blog/2018/04/16/post-title (/index.html file)?

Lastly, for making content available, it's related to this line when siteData is being built. What would be an elegant solution to enable content in siteData, for feed?

@yeedle

This comment has been minimized.

yeedle commented Apr 19, 2018

running vuepress build rebuilds the entire website which makes sense for a documentation website but not as much for a blog. Is there a straightforward approach to build just the newly added pages?

@andreasvirkus

This comment has been minimized.

andreasvirkus commented Apr 21, 2018

Also linking this here (RSS support was already mentioned above) to keep sitemaps in mind.
Maybe the other ticket can be closed then? 🤷‍♂️
#52

Other things that my current Metalsmith blog supports and we could implement very easily (sorta nice-to-have features, but at the same time standards nowadays, I suppose):

  • time to read/word count
  • last modified/published date
  • title case for post titles (?)

Maybe also think about nesting themes? So if / uses the default/docs theme, then /blog could use a separate theme and gather everything from blog/*.md as posts? Or should this be solved via themeConfig.docsDir and have two separate builds?

@ycmjason

This comment has been minimized.

Contributor

ycmjason commented Apr 21, 2018

A little bit irrelevant but I have written some really hacky code to make the current VuePress looks a little bit more like a blog with the following config.

https://github.com/ycmjason/ycmjason.com/blob/master/.vuepress/config.js

It will automatically generated a side bar with "YYYY MMM" format and then the title of the article would have the date prepended. So I could now easily add a new article without worrying about adding them to side bar.

See the blog live here:

https://www.ycmjason.com

@rogersachan

This comment has been minimized.

rogersachan commented Apr 23, 2018

Support for comments using disqus or the like would be welcome as well.

@ycmjason

This comment has been minimized.

Contributor

ycmjason commented Apr 23, 2018

@rogersachan planning to do that for my site. And also planning to add tags support.

@tdurieux

This comment has been minimized.

tdurieux commented Apr 24, 2018

Thanks @mdaffin and @ycmjason, I used your code to create a first version of my blog.
It works, ok. I still need to figure out how to handle to tags in the current version

@Deadalusmask

This comment has been minimized.

Deadalusmask commented Apr 27, 2018

Thanks for this discussion, I just migrated my blog from hexo, check Deadalusmask/Arthas.me if it helps. 😁
Arthas.me

And also hope for news about disqus support.

@eyleron

This comment has been minimized.

eyleron commented Apr 27, 2018

Documentation versus Blog Features

I've been looking at the VuePress issues and progress and the push to milestone. I totally get drawing a line between "core documentation use case" versus "blog use case". But I think that too can be a form of trap where features that are useful "core features" or "documentation features" get split off into an either/or system.

For my company's software documentation, I'm thinking on using VuePress, and so we could definitely use some of these features that some would consider more "bloggy".

  • Categories

  • Tags: not just for display per-page, but also as an alternative means of organizing/navigating content.
    For instance, many help documentation systems support multiple "builds" whereby tag variables trigger alternative versions of the content. For instance, a "Platinum" build might include all of the feature documentation. Or, in VuePress' case, one build of documentation might be "Core + Documentation" and the other build would be "Core + Blog".

  • Last Updated

@mdaffin

This comment has been minimized.

Contributor

mdaffin commented Apr 28, 2018

@eyleron once the plugin system gets released then things should be more composable. Ideally, it would be nice to keep the core features light and implement most optional features in plugins or separate themes rather than bloating down the core with every possible feature people could want.

Even common things like tags and categories can be harder to make generic across a blog and docs and I think it would be better first designing these features in plugins and themes where there is more freedom to try things out and experiment before setting on a design for things if one can be found. I know I for one have found the tagging system of some static site generators to be limiting for what I wanted to do at times.

@luisDanielRoviraContreras

This comment has been minimized.

Contributor

luisDanielRoviraContreras commented Apr 29, 2018

An improvement that I think is needed is to be able to add a label in the menu that says example component x (New) or component x (updated) something like this
screenshot_30

I would love to help in this

@meteorlxy

This comment has been minimized.

Contributor

meteorlxy commented Apr 29, 2018

@luisDanielRoviraContreras
That's cool, but may not in this blog roadmap

@awulkan

This comment has been minimized.

awulkan commented Jun 25, 2018

@octref So you don't want smoother loading like the example I created here?
https://vp-urls.netlify.com/

Then you wouldn't have to rely on your host to handle the routing at all, and no page reloads would be necessary. Of course you're free to do whatever you want to, just asking. :)

@octref

This comment has been minimized.

Member

octref commented Jun 25, 2018

@awulkan @rayfoss I see your point, but I'm not sold on PWA. Guess we just want different things (I talked more about this in #602), and I can happily live in my own fork or build my own thing.

For https://vp-urls.netlify.com,

image

This is my model of static website: https://apex.sh

image

What I want is something similar to https://github.com/apex/static.

I think Vuepress should be the most well executed static PWA renderer for personal websites, not just another static site generator like Hexo/Jekyll.

I think that's covered by Nuxt, but anyway, if that's Vuepress's vision, I wish you good luck and I'll build something different.

@awulkan

This comment has been minimized.

awulkan commented Jun 25, 2018

@octref I get what you're saying, I just wonder if VuePress is the right choice for you (or me for that matter). It just doesn't feel right to break the built in client side routing.

I would use the same tactic as you are to get clean URLs, if i knew that it would be the intended way for Vuepress to work. It would suck to build a website with vuepress and then have to change to another generator if the hack you're using now doesn't work anymore all of a sudden.

@awulkan

This comment has been minimized.

awulkan commented Jun 28, 2018

@octref Just wanted to tell you that you can put this in your config file:

shouldPrefetch: (file, type) => {
    return false;
}

https://vuepress.vuejs.org/config/#shouldprefetch

And it will not pre-load everything. It will just load the files needed for the specific page you are on.

If we can get the "pretty url" stuff that I talked about in my github issue, then you should be able to get VuePress working as you want it, without having to rely on your host's routing, and doing a full page reload between each route change.

Using shoudPrefetch will probably be necessary for most larger blogs.

@ulivz ulivz closed this Aug 20, 2018

@mathiasbynens

This comment has been minimized.

mathiasbynens commented Aug 20, 2018

@ulivz Why was this closed? Is there some other issue or place we can track for updates on blog functionality support in VuePress?

@ulivz

This comment has been minimized.

Member

ulivz commented Aug 20, 2018

@mathiasbynens

Thanks for your concern, I just found too many irrelevant discussions, and we are developing an official blog theme, and once the official blog is basically completed, I think it would be more appropriate to reopen a targeted discussion.

@mathiasbynens

This comment has been minimized.

mathiasbynens commented Aug 20, 2018

That’s great to hear! Can folks track the status of the official blog theme anywhere? (Is there a repo yet?)

@ulivz

This comment has been minimized.

Member

ulivz commented Aug 20, 2018

After the official blog is basically completed, I will inform everyone here and provide a link to continue the discussion. (I believe it should be within a week.)

@octref

This comment has been minimized.

Member

octref commented Aug 20, 2018

@ulivz Then why don't you keep this issue open, if there is no other issue tracking blog support yet? Or better yet, create a new issue that describes what you plan to do for the "Official Blog Theme".

You don't need to create issue only after "basically completed". Just having an issue that says what you plan to do helps keeping everyone updated.

@yyx990803

This comment has been minimized.

Member

yyx990803 commented Aug 20, 2018

I actually think the non-js / pure-static usage is something we might want to consider supporting. Something like a "purely static mode", mostly because it seems to be a low-hanging fruit that can broaden the use case. Purely static pages do have the advantage of smaller payload and less JavaScript execution.

After @ulivz is done with the refactoring in the next branch we can take a few PRs to add support for:

  1. A cleanUrl option to generate clean urls for static services that support it.

  2. Purely static mode (mostly just dropping the scripts in the rendered HTML)

@octref

This comment has been minimized.

Member

octref commented Aug 20, 2018

@yyx990803 Thanks for your insights! I actually created both issue a while ago:

  1. Clean URL: #603
  2. Purely static mode (I'll reopen this then): #602
@ulivz

This comment has been minimized.

Member

ulivz commented Aug 23, 2018

1st step of blog support, permalink has been basically completed: #763

@ulivz ulivz reopened this Aug 23, 2018

@xkcoding

This comment has been minimized.

xkcoding commented Aug 24, 2018

excellent!

@rdwatters

This comment has been minimized.

rdwatters commented Aug 25, 2018

This is such a cool and exciting project. With all these comments, I've noticed multiple mentions of "tags" and "categories" and the idea of "blog support". I think a more flexible and future-friendly mindset is to not limit things to just these categorizations and not think only of a "blog," which is a limited mental model/content ontology as sites start to grow; e.g.— this is why sites with really complex relationships between content become unmanageable with Wordpress, and why platforms like Jekyll have trouble breaking out of the dev-o-sphere.

I really like the more abstracted approach to taxonomies that Hugo uses. Content managers can then arbitrarily define controlled vocabularies (or even folksonomies, if you're intro crazy-makers) that can be used for navigation (e.g. Wired.com's use of WP categories for global nav), or just to define related articles by making taxonomic weight configurable at the site level without having taxonomies necessarily rendered to user-visible pages.

Naturally, everything else sounds good too; e.g., permalinks, redirects, etc...

@robmuh

This comment has been minimized.

robmuh commented Sep 16, 2018

Please, please do not turn the default theme into yet another blogging engine. This is what makes VuePress unique and preferred for other content besides blogging. One of the biggest failures of the Hugo project is the blog model built into every component of it from the start.

Consider as well the existing PWA/app support built into the default theme. This static/cache-first integration is absolutely amazing and allows VuePress to replace other portable document solutions. The idea itself is somewhat at odds with dynamic, perhaps daily blogging and integration of comment threads.

I'm good with adding all these blog-centric things through configuration to even the default theme, but clearly the easiest solution is to produce one or more blog-centric themes to choose from and leave the basic VuePress documentation-centric model alone.

@willin

This comment has been minimized.

willin commented Sep 19, 2018

pls set up a doc domain for next version vuepress.

@ulivz

This comment has been minimized.

Member

ulivz commented Sep 19, 2018

@robmuh Of course we don't plan to turn the default theme into yet another blogging engine. actually all the blog features has been done by plugins, so the original features that VuePress has will not be changed.

@ulivz

This comment has been minimized.

Member

ulivz commented Sep 19, 2018

@willin we have set the Netlify build for each PR, so you can check out the deploy site:

  1. Documentation (Updating): https://deploy-preview-815--vuepress.netlify.com/plugin/
  2. Blog Showcase (Updating): http://www.v2js.com/vuepress-theme-egoist/
  3. Blog Showcase source (Updating): https://github.com/ulivz/vuepress-theme-egoist

With plugin @vuepress/plugin-blog and @vuepress/plugin-pagination, writing a blog theme will be very simple.

@ulivz

This comment has been minimized.

Member

ulivz commented Sep 19, 2018

About publishing, we plan to release the alpha version at 25th of this month. —— The rest of the work is basically to write documentation and migration help, I hope I can complete them ASAP.

@ulivz

This comment has been minimized.

Member

ulivz commented Sep 19, 2018

BTW, is there a desiger(familiar to AI or Sketch) who wants to join the design of the official blog theme?

Some design principles:

  1. Follow the UX of Vue.
  2. Try to keep consistent with @vue/ui.

// cc @Akryum

@vuejs vuejs deleted a comment from willin Sep 19, 2018

@vuejs vuejs deleted a comment from willin Sep 19, 2018

@vuejs vuejs deleted a comment from visamz Sep 26, 2018

@lekevicius

This comment has been minimized.

Collaborator

lekevicius commented Sep 28, 2018

@ulivz I'm a UI / product designer, spend all my time in Sketch and would love to design a blog theme.

@martinsotirov

This comment has been minimized.

Contributor

martinsotirov commented Oct 1, 2018

I would be happy with essentially a Hugo clone that uses Vue.js for the templates.

@ulivz

This comment has been minimized.

Member

ulivz commented Oct 21, 2018

@lekevicius So excited to know that you want to join in the design of the blog theme, my twitter is @_ulivz, let's talk privately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment